@principal-ai/subsystems-core 0.29.0

package/src/rules/implementations/state-transition-references.ts

@@ -0,0 +1,155 @@
+/**
+ * Rule: state-transition-references
+ * Ensures state transitions only reference defined states
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const stateTransitionReferences: GraphRule = {
+  id: 'state-transition-references',
+  name: 'State Transition References',
+  description: 'State transitions must reference states defined in nodeTypes',
+  impact: 'Invalid state references will cause state 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.validation?.stateTransitions) {
+      return violations;
+    }
+
+    // Build a map of nodeType -> defined states
+    const statesByNodeType = new Map<string, Set<string>>();
+
+    if (configuration.nodeTypes) {
+      for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
+        if (nodeType.states) {
+          statesByNodeType.set(typeId, new Set(Object.keys(nodeType.states)));
+        }
+      }
+    }
+
+    // Check each state transition rule
+    for (const [nodeTypeId, transitions] of Object.entries(
+      configuration.validation.stateTransitions
+    )) {
+      const basePath = `validation.stateTransitions.${nodeTypeId}`;
+
+      // Check if nodeType exists
+      if (!configuration.nodeTypes?.[nodeTypeId]) {
+        violations.push({
+          ruleId: 'state-transition-references',
+          severity: 'error',
+          file: configPath,
+          path: basePath,
+          message: `State transitions defined for undefined nodeType "${nodeTypeId}"`,
+          impact: 'These state transitions will never apply',
+          suggestion: `Available nodeTypes: ${
+            Object.keys(configuration.nodeTypes ?? {}).join(', ') || '(none defined)'
+          }`,
+          fixable: false,
+        });
+        continue;
+      }
+
+      // Check if nodeType has states defined
+      const definedStates = statesByNodeType.get(nodeTypeId);
+      if (!definedStates || definedStates.size === 0) {
+        violations.push({
+          ruleId: 'state-transition-references',
+          severity: 'error',
+          file: configPath,
+          path: basePath,
+          message: `State transitions defined for nodeType "${nodeTypeId}" which has no states`,
+          impact: 'These state transitions will never apply',
+          suggestion: `Add states to nodeTypes.${nodeTypeId}.states`,
+          fixable: false,
+        });
+        continue;
+      }
+
+      // Check each transition
+      if (Array.isArray(transitions)) {
+        for (let i = 0; i < transitions.length; i++) {
+          const transition = transitions[i];
+          const transitionPath = `${basePath}[${i}]`;
+
+          // Check 'from' state
+          if (transition.from && !definedStates.has(transition.from)) {
+            const suggestion = findSimilar(transition.from, definedStates);
+            violations.push({
+              ruleId: 'state-transition-references',
+              severity: 'error',
+              file: configPath,
+              path: `${transitionPath}.from`,
+              message: `Transition references undefined state "${transition.from}" in nodeType "${nodeTypeId}"`,
+              impact: 'This transition will never match',
+              suggestion: suggestion
+                ? `Did you mean "${suggestion}"?`
+                : `Available states: ${[...definedStates].join(', ')}`,
+              fixable: false,
+            });
+          }
+
+          // Check 'to' states
+          if (Array.isArray(transition.to)) {
+            for (let j = 0; j < transition.to.length; j++) {
+              const toState = transition.to[j];
+              if (!definedStates.has(toState)) {
+                const suggestion = findSimilar(toState, definedStates);
+                violations.push({
+                  ruleId: 'state-transition-references',
+                  severity: 'error',
+                  file: configPath,
+                  path: `${transitionPath}.to[${j}]`,
+                  message: `Transition references undefined state "${toState}" in nodeType "${nodeTypeId}"`,
+                  impact: 'This transition target is invalid',
+                  suggestion: suggestion
+                    ? `Did you mean "${suggestion}"?`
+                    : `Available states: ${[...definedStates].join(', ')}`,
+                  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/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,140 @@
+/**
+ * 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,152 @@
+/**
+ * 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 },
+  };
+}