@principal-ai/principal-view-core 0.5.6

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

@@ -0,0 +1,189 @@
+/**
+ * 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 animation types
+ */
+const VALID_ANIMATION_TYPES = ['flow', 'pulse', 'particle', 'glow'] 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 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

@@ -0,0 +1,95 @@
+/**
+ * Rules Engine - Configuration validation for Visual Validation Framework
+ *
+ * @example
+ * ```typescript
+ * import { createRulesEngine, builtinRules } from '@principal-ai/principal-view-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,
+  // Library rules
+  libraryNodeTypeMatch,
+  // Rule option types
+  type MinimumNodeSourcesOptions,
+  type DeadEndStatesOptions,
+  type ValidActionPatternsOptions,
+  type LibraryNodeTypeMatchOptions,
+} 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);
+}

package/src/rules/types.ts

@@ -0,0 +1,426 @@
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+
+// ============================================================================
+// Rule Severity and Categories
+// ============================================================================
+
+/**
+ * Severity levels following ESLint convention
+ * - "off" or 0: Disable rule
+ * - "warn" or 1: Warning (doesn't affect exit code)
+ * - "error" or 2: Error (exit code 1)
+ */
+export type RuleSeverity = 'off' | 'warn' | 'error' | 0 | 1 | 2;
+
+/**
+ * Normalized severity (string form only)
+ */
+export type NormalizedSeverity = 'off' | 'warn' | 'error';
+
+/**
+ * Rule categories for grouping and filtering
+ */
+export type RuleCategory = 'schema' | 'reference' | 'structure' | 'pattern' | 'library';
+
+// ============================================================================
+// Rule Configuration (RC File)
+// ============================================================================
+
+/**
+ * Full rule configuration object
+ */
+export interface RuleConfig {
+  /**
+   * Rule severity
+   * @default "error"
+   */
+  severity?: RuleSeverity;
+
+  /**
+   * Rule-specific options
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * VGC Configuration file schema
+ */
+export interface PrivuConfig {
+  /**
+   * Schema version for forward compatibility
+   */
+  $schema?: string;
+
+  /**
+   * Extend from a shared configuration
+   * Can be a package name or relative path
+   */
+  extends?: string | string[];
+
+  /**
+   * Root flag - stop searching parent directories
+   * @default false
+   */
+  root?: boolean;
+
+  /**
+   * Path to default component library
+   * Used by library-node-type-match rule
+   */
+  library?: string;
+
+  /**
+   * Glob patterns for configuration files to lint
+   * @default [".vgc/**\/*.yaml", ".vgc/**\/*.yml", ".vgc/**\/*.json"]
+   */
+  include?: string[];
+
+  /**
+   * Glob patterns to exclude from linting
+   * @default ["**\/node_modules/**", "**\/*.test.*"]
+   */
+  exclude?: string[];
+
+  /**
+   * Rule configurations
+   */
+  rules?: {
+    [ruleId: string]: RuleConfig | RuleSeverity | false;
+  };
+}
+
+// ============================================================================
+// Rule Definition
+// ============================================================================
+
+/**
+ * Rule-specific options type (varies per rule)
+ */
+export type RuleOptions = Record<string, unknown>;
+
+/**
+ * Definition of a validation rule
+ */
+export interface GraphRule<TOptions extends RuleOptions = RuleOptions> {
+  /**
+   * Unique rule identifier (kebab-case)
+   */
+  id: string;
+
+  /**
+   * Human-readable rule name
+   */
+  name: string;
+
+  /**
+   * Brief description of what the rule checks
+   */
+  description: string;
+
+  /**
+   * Explanation of why this rule matters
+   */
+  impact: string;
+
+  /**
+   * Default severity level
+   * @default "error"
+   */
+  severity: NormalizedSeverity;
+
+  /**
+   * Rule category for grouping
+   */
+  category: RuleCategory;
+
+  /**
+   * Whether the rule is enabled by default
+   * @default true
+   */
+  enabled: boolean;
+
+  /**
+   * Whether the rule supports auto-fix
+   * @default false
+   */
+  fixable: boolean;
+
+  /**
+   * Default options for this rule
+   */
+  defaultOptions?: TOptions;
+
+  /**
+   * Execute the rule check
+   */
+  check: (context: GraphRuleContext<TOptions>) => Promise<GraphRuleViolation[]>;
+
+  /**
+   * Optional auto-fix implementation
+   */
+  fix?: (violation: GraphRuleViolation, context: GraphRuleContext<TOptions>) => Promise<FixResult>;
+}
+
+// ============================================================================
+// Rule Context
+// ============================================================================
+
+import type { GraphConfiguration } from '../types';
+import type { ComponentLibrary } from '../types/library';
+
+/**
+ * Context passed to rules during evaluation
+ */
+export interface GraphRuleContext<TOptions extends RuleOptions = RuleOptions> {
+  /**
+   * The configuration being validated
+   */
+  configuration: GraphConfiguration;
+
+  /**
+   * Optional component library for library rules
+   */
+  library?: ComponentLibrary;
+
+  /**
+   * Path to the configuration file (for error reporting)
+   */
+  configPath?: string;
+
+  /**
+   * Path to the library file (for error reporting)
+   */
+  libraryPath?: string;
+
+  /**
+   * Raw YAML/JSON string (for line number lookup)
+   */
+  rawContent?: string;
+
+  /**
+   * Rule-specific options (merged with defaults)
+   */
+  options: TOptions;
+
+  /**
+   * All rule options from config (for cross-rule access if needed)
+   */
+  allRuleOptions?: Map<string, RuleOptions>;
+}
+
+// ============================================================================
+// Rule Violations
+// ============================================================================
+
+/**
+ * A violation detected by a rule
+ */
+export interface GraphRuleViolation {
+  /**
+   * ID of the rule that detected this violation
+   */
+  ruleId: string;
+
+  /**
+   * Severity of this violation
+   */
+  severity: NormalizedSeverity;
+
+  /**
+   * Path to the file containing the violation
+   */
+  file?: string;
+
+  /**
+   * Line number in the file (1-indexed)
+   */
+  line?: number;
+
+  /**
+   * Column number in the file (1-indexed)
+   */
+  column?: number;
+
+  /**
+   * JSON path to the problematic field (e.g., "nodeTypes.service.shape")
+   */
+  path?: string;
+
+  /**
+   * Clear, actionable error message
+   */
+  message: string;
+
+  /**
+   * Explanation of why this matters
+   */
+  impact: string;
+
+  /**
+   * Suggestion for how to fix
+   */
+  suggestion?: string;
+
+  /**
+   * Whether this violation can be auto-fixed
+   */
+  fixable: boolean;
+
+  /**
+   * Data needed for auto-fix
+   */
+  fixData?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Lint Results
+// ============================================================================
+
+/**
+ * Result of running all rules
+ */
+export interface GraphLintResult {
+  /**
+   * All violations found
+   */
+  violations: GraphRuleViolation[];
+
+  /**
+   * Count of error-level violations
+   */
+  errorCount: number;
+
+  /**
+   * Count of warning-level violations
+   */
+  warningCount: number;
+
+  /**
+   * Count of fixable violations
+   */
+  fixableCount: number;
+
+  /**
+   * Violations grouped by category
+   */
+  byCategory: Record<RuleCategory, number>;
+
+  /**
+   * Violations grouped by rule ID
+   */
+  byRule: Record<string, number>;
+}
+
+// ============================================================================
+// Fix Results
+// ============================================================================
+
+/**
+ * Result of attempting to fix a violation
+ */
+export interface FixResult {
+  /**
+   * Whether the fix was successful
+   */
+  success: boolean;
+
+  /**
+   * Description of what was fixed
+   */
+  message?: string;
+
+  /**
+   * New content after fix (if applicable)
+   */
+  newContent?: string;
+
+  /**
+   * Error message if fix failed
+   */
+  error?: string;
+}
+
+// ============================================================================
+// Lint Options
+// ============================================================================
+
+/**
+ * Options for the lint operation
+ */
+export interface LintOptions {
+  /**
+   * Only run these rules (by ID)
+   */
+  enabledRules?: string[];
+
+  /**
+   * Skip these rules (by ID)
+   */
+  disabledRules?: string[];
+
+  /**
+   * Override severity for specific rules
+   */
+  severityOverrides?: Map<string, NormalizedSeverity>;
+
+  /**
+   * Component library for library rules
+   */
+  library?: ComponentLibrary;
+
+  /**
+   * Path to config file (for error reporting)
+   */
+  configPath?: string;
+
+  /**
+   * Path to library file (for error reporting)
+   */
+  libraryPath?: string;
+
+  /**
+   * Raw content for line number reporting
+   */
+  rawContent?: string;
+
+  /**
+   * Rule-specific options
+   */
+  ruleOptions?: Map<string, RuleOptions>;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Normalize severity to string form
+ */
+export function normalizeSeverity(severity: RuleSeverity): NormalizedSeverity {
+  if (typeof severity === 'number') {
+    switch (severity) {
+      case 0:
+        return 'off';
+      case 1:
+        return 'warn';
+      case 2:
+        return 'error';
+      default:
+        return 'error';
+    }
+  }
+  return severity;
+}
+
+/**
+ * Check if a severity means the rule is disabled
+ */
+export function isRuleDisabled(severity: RuleSeverity | false | undefined): boolean {
+  if (severity === false || severity === 'off' || severity === 0) {
+    return true;
+  }
+  return false;
+}