@principal-ai/subsystems-core 0.29.0 → 0.31.0

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

@@ -1,273 +0,0 @@
-/**
- * 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;
-  },
-};

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

@@ -1,200 +0,0 @@
-/**
- * Rule: valid-node-types
- * Ensures nodeTypes have required fields and valid values
- */
-
-import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
-
-/**
- * Valid shape values for nodes
- */
-const VALID_SHAPES = ['circle', 'rectangle', 'hexagon', 'diamond', 'custom'] as const;
-
-/**
- * Valid data schema field types
- */
-const VALID_DATA_TYPES = ['string', 'number', 'boolean', 'object', 'array'] as const;
-
-export const validNodeTypes: GraphRule = {
-  id: 'valid-node-types',
-  name: 'Valid Node Types',
-  description: 'nodeTypes must have required fields and valid values',
-  impact: 'Invalid node 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.nodeTypes) {
-      violations.push({
-        ruleId: 'valid-node-types',
-        severity: 'error',
-        file: configPath,
-        path: 'nodeTypes',
-        message: 'Configuration is missing nodeTypes section',
-        impact: 'No nodes can be defined without nodeTypes',
-        suggestion: 'Add a nodeTypes section with at least one node type definition',
-        fixable: false,
-      });
-      return violations;
-    }
-
-    if (Object.keys(configuration.nodeTypes).length === 0) {
-      violations.push({
-        ruleId: 'valid-node-types',
-        severity: 'error',
-        file: configPath,
-        path: 'nodeTypes',
-        message: 'nodeTypes section is empty',
-        impact: 'No nodes can be defined without at least one node type',
-        suggestion: 'Add at least one node type definition',
-        fixable: false,
-      });
-      return violations;
-    }
-
-    for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
-      const basePath = `nodeTypes.${typeId}`;
-
-      // Check required description field
-      if (!nodeType.description) {
-        violations.push({
-          ruleId: 'valid-node-types',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.description`,
-          message: `Node type "${typeId}" is missing required "description" field`,
-          impact: 'Node type must have a description explaining its purpose',
-          suggestion: 'Add a description field explaining what this node type represents',
-          fixable: false,
-        });
-      }
-
-      // Check required shape field
-      if (!nodeType.shape) {
-        violations.push({
-          ruleId: 'valid-node-types',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.shape`,
-          message: `Node type "${typeId}" is missing required "shape" field`,
-          impact: 'Node cannot be rendered without a shape',
-          suggestion: `Add a shape field. Valid values: ${VALID_SHAPES.join(', ')}`,
-          fixable: false,
-        });
-      } else if (!VALID_SHAPES.includes(nodeType.shape as (typeof VALID_SHAPES)[number])) {
-        violations.push({
-          ruleId: 'valid-node-types',
-          severity: 'error',
-          file: configPath,
-          path: `${basePath}.shape`,
-          message: `Node type "${typeId}" has invalid shape "${nodeType.shape}"`,
-          impact: 'Node may not render correctly',
-          suggestion: `Valid shapes: ${VALID_SHAPES.join(', ')}`,
-          fixable: false,
-        });
-      }
-
-      // Check dataSchema field types
-      if (nodeType.dataSchema) {
-        for (const [fieldName, fieldDef] of Object.entries(nodeType.dataSchema)) {
-          if (!fieldDef.type) {
-            violations.push({
-              ruleId: 'valid-node-types',
-              severity: 'error',
-              file: configPath,
-              path: `${basePath}.dataSchema.${fieldName}.type`,
-              message: `Data schema field "${fieldName}" in node 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-node-types',
-              severity: 'error',
-              file: configPath,
-              path: `${basePath}.dataSchema.${fieldName}.type`,
-              message: `Invalid data type "${fieldDef.type}" for field "${fieldName}" in node type "${typeId}"`,
-              impact: 'Data validation may fail',
-              suggestion: `Valid types: ${VALID_DATA_TYPES.join(', ')}`,
-              fixable: false,
-            });
-          }
-        }
-      }
-
-      // Check states have valid structure
-      if (nodeType.states) {
-        for (const [stateName, stateDef] of Object.entries(nodeType.states)) {
-          // States should be objects (even if empty)
-          if (typeof stateDef !== 'object' || stateDef === null) {
-            violations.push({
-              ruleId: 'valid-node-types',
-              severity: 'error',
-              file: configPath,
-              path: `${basePath}.states.${stateName}`,
-              message: `State "${stateName}" in node type "${typeId}" must be an object`,
-              impact: 'State definition is invalid',
-              suggestion: 'State should be an object with optional color, icon, and label fields',
-              fixable: false,
-            });
-          }
-        }
-      }
-
-      // Check size has valid structure
-      if (nodeType.size) {
-        if (typeof nodeType.size.width !== 'number' || typeof nodeType.size.height !== 'number') {
-          violations.push({
-            ruleId: 'valid-node-types',
-            severity: 'error',
-            file: configPath,
-            path: `${basePath}.size`,
-            message: `Node type "${typeId}" size must have numeric width and height`,
-            impact: 'Node size may not render correctly',
-            suggestion: 'Provide size as { width: number, height: number }',
-            fixable: false,
-          });
-        }
-      }
-
-      // Check layout has valid structure
-      if (nodeType.layout) {
-        if (nodeType.layout.layer !== undefined && typeof nodeType.layout.layer !== 'number') {
-          violations.push({
-            ruleId: 'valid-node-types',
-            severity: 'error',
-            file: configPath,
-            path: `${basePath}.layout.layer`,
-            message: `Node type "${typeId}" layout.layer must be a number`,
-            impact: 'Layout layering may not work correctly',
-            suggestion: 'Provide layer as a number',
-            fixable: false,
-          });
-        }
-
-        if (nodeType.layout.cluster !== undefined && typeof nodeType.layout.cluster !== 'string') {
-          violations.push({
-            ruleId: 'valid-node-types',
-            severity: 'error',
-            file: configPath,
-            path: `${basePath}.layout.cluster`,
-            message: `Node type "${typeId}" layout.cluster must be a string`,
-            impact: 'Cluster grouping may not work correctly',
-            suggestion: 'Provide cluster as a string identifier',
-            fixable: false,
-          });
-        }
-      }
-    }
-
-    return violations;
-  },
-};

package/src/rules/index.ts

@@ -1,92 +0,0 @@
-/**
- * Rules Engine - Configuration validation for Visual Validation Framework
- *
- * @example
- * ```typescript
- * import { createRulesEngine, builtinRules } from '@principal-ai/subsystems-core/rules';
- *
- * const engine = createRulesEngine(builtinRules);
- * const result = await engine.lint(configuration);
- *
- * if (result.errorCount > 0) {
- *   console.error(`Found ${result.errorCount} errors`);
- *   for (const violation of result.violations) {
- *     console.error(`  ${violation.path}: ${violation.message}`);
- *   }
- * }
- * ```
- */
-
-// Core engine
-export { GraphRulesEngine, createRulesEngine } from './engine';
-
-// Types
-export type {
-  GraphRule,
-  GraphRuleContext,
-  GraphRuleViolation,
-  GraphLintResult,
-  LintOptions,
-  RuleOptions,
-  RuleSeverity,
-  NormalizedSeverity,
-  RuleCategory,
-  RuleConfig,
-  PrivuConfig,
-  FixResult,
-} from './types';
-
-export { normalizeSeverity, isRuleDisabled } from './types';
-
-// Config validation
-export {
-  validatePrivuConfig,
-  getDefaultConfig,
-  mergeConfigs,
-  formatConfigErrors,
-  CONFIG_FILE_NAMES,
-  DEFAULT_INCLUDE_PATTERNS,
-  DEFAULT_EXCLUDE_PATTERNS,
-  VALID_RULE_IDS,
-  VALID_SEVERITIES,
-  type ConfigValidationError,
-  type ConfigValidationResult,
-  type ValidRuleId,
-} from './config';
-
-// Built-in rules
-export {
-  builtinRules,
-  // Schema rules
-  requiredMetadata,
-  validNodeTypes,
-  validEdgeTypes,
-  validColorFormat,
-  noUnknownFields,
-  // Reference rules
-  connectionTypeReferences,
-  stateTransitionReferences,
-  // Structure rules
-  minimumNodeSources,
-  orphanedNodeTypes,
-  orphanedEdgeTypes,
-  unreachableStates,
-  deadEndStates,
-  // Pattern rules
-  validActionPatterns,
-  // Rule option types
-  type MinimumNodeSourcesOptions,
-  type DeadEndStatesOptions,
-  type ValidActionPatternsOptions,
-} from './implementations';
-
-// Convenience factory that creates an engine with all built-in rules
-import { createRulesEngine } from './engine';
-import { builtinRules } from './implementations';
-
-/**
- * Create a rules engine pre-configured with all built-in rules
- */
-export function createDefaultRulesEngine() {
-  return createRulesEngine(builtinRules);
-}