@principal-ai/principal-view-core 0.5.6

package/src/rules/implementations/no-unknown-fields.ts

@@ -0,0 +1,342 @@
+/**
+ * Rule: no-unknown-fields
+ * Flags fields that are not defined in the configuration schema
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+/**
+ * Allowed fields for each configuration section
+ */
+const ALLOWED_FIELDS = {
+  root: ['metadata', 'nodeTypes', 'edgeTypes', 'allowedConnections', 'validation', 'display'],
+  metadata: ['name', 'version', 'description'],
+  nodeType: [
+    'shape',
+    'icon',
+    'color',
+    'stroke',
+    'size',
+    'dataSchema',
+    'states',
+    'layout',
+    'sources',
+    'actions',
+  ],
+  edgeType: [
+    'style',
+    'color',
+    'width',
+    'directed',
+    'animated',
+    'label',
+    'animation',
+    'dataSchema',
+    'activatedBy',
+  ],
+  connectionRule: ['from', 'to', 'via', 'constraints'],
+  connectionConstraints: ['maxInstances', 'bidirectional', 'exclusive'],
+  validation: ['stateTransitions', 'constraints', 'cardinality'],
+  display: ['layout', 'theme', 'animations'],
+  displayTheme: ['primary', 'success', 'warning', 'danger', 'info'],
+  displayAnimations: ['enabled', 'speed'],
+  dataSchemaField: ['type', 'required', 'displayInLabel', 'label', 'displayInInfo'],
+  stateDefinition: ['color', 'icon', 'label'],
+  layoutHints: ['layer', 'cluster'],
+  edgeLabel: ['field', 'position'],
+  edgeAnimation: ['type', 'duration', 'color'],
+  nodeSize: ['width', 'height'],
+  stateTransition: ['from', 'to'],
+  constraint: ['id', 'description', 'check', 'severity'],
+  actionPattern: ['pattern', 'event', 'state', 'metadata'],
+};
+
+export const noUnknownFields: GraphRule = {
+  id: 'no-unknown-fields',
+  name: 'No Unknown Fields',
+  description: 'Flag fields that are not defined in the configuration schema',
+  impact: 'Unknown fields are likely typos and will be ignored',
+  severity: 'error',
+  category: 'schema',
+  enabled: true,
+  fixable: true,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    // Check root level fields
+    checkFields(configuration as unknown as Record<string, unknown>, ALLOWED_FIELDS.root, '', configPath, violations);
+
+    // Check metadata fields
+    if (configuration.metadata) {
+      checkFields(
+        configuration.metadata as Record<string, unknown>,
+        ALLOWED_FIELDS.metadata,
+        'metadata',
+        configPath,
+        violations
+      );
+    }
+
+    // Check nodeTypes
+    if (configuration.nodeTypes) {
+      for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
+        const basePath = `nodeTypes.${typeId}`;
+        checkFields(nodeType as unknown as Record<string, unknown>, ALLOWED_FIELDS.nodeType, basePath, configPath, violations);
+
+        // Check nested fields in nodeType
+        if (nodeType.dataSchema) {
+          for (const [fieldName, fieldDef] of Object.entries(nodeType.dataSchema)) {
+            checkFields(
+              fieldDef as Record<string, unknown>,
+              ALLOWED_FIELDS.dataSchemaField,
+              `${basePath}.dataSchema.${fieldName}`,
+              configPath,
+              violations
+            );
+          }
+        }
+
+        if (nodeType.states) {
+          for (const [stateName, stateDef] of Object.entries(nodeType.states)) {
+            checkFields(
+              stateDef as Record<string, unknown>,
+              ALLOWED_FIELDS.stateDefinition,
+              `${basePath}.states.${stateName}`,
+              configPath,
+              violations
+            );
+          }
+        }
+
+        if (nodeType.layout) {
+          checkFields(
+            nodeType.layout as Record<string, unknown>,
+            ALLOWED_FIELDS.layoutHints,
+            `${basePath}.layout`,
+            configPath,
+            violations
+          );
+        }
+
+        if (nodeType.size) {
+          checkFields(
+            nodeType.size as Record<string, unknown>,
+            ALLOWED_FIELDS.nodeSize,
+            `${basePath}.size`,
+            configPath,
+            violations
+          );
+        }
+
+        // Check actions
+        const nodeTypeAny = nodeType as unknown as Record<string, unknown>;
+        if (Array.isArray(nodeTypeAny.actions)) {
+          (nodeTypeAny.actions as unknown[]).forEach((action: unknown, index: number) => {
+            if (typeof action === 'object' && action !== null) {
+              checkFields(
+                action as Record<string, unknown>,
+                ALLOWED_FIELDS.actionPattern,
+                `${basePath}.actions[${index}]`,
+                configPath,
+                violations
+              );
+            }
+          });
+        }
+      }
+    }
+
+    // Check edgeTypes
+    if (configuration.edgeTypes) {
+      for (const [typeId, edgeType] of Object.entries(configuration.edgeTypes)) {
+        const basePath = `edgeTypes.${typeId}`;
+        checkFields(edgeType as unknown as Record<string, unknown>, ALLOWED_FIELDS.edgeType, basePath, configPath, violations);
+
+        if (edgeType.label && typeof edgeType.label === 'object') {
+          checkFields(
+            edgeType.label as Record<string, unknown>,
+            ALLOWED_FIELDS.edgeLabel,
+            `${basePath}.label`,
+            configPath,
+            violations
+          );
+        }
+
+        if (edgeType.animation && typeof edgeType.animation === 'object') {
+          checkFields(
+            edgeType.animation as Record<string, unknown>,
+            ALLOWED_FIELDS.edgeAnimation,
+            `${basePath}.animation`,
+            configPath,
+            violations
+          );
+        }
+
+        if (edgeType.dataSchema) {
+          for (const [fieldName, fieldDef] of Object.entries(edgeType.dataSchema)) {
+            checkFields(
+              fieldDef as Record<string, unknown>,
+              ALLOWED_FIELDS.dataSchemaField,
+              `${basePath}.dataSchema.${fieldName}`,
+              configPath,
+              violations
+            );
+          }
+        }
+      }
+    }
+
+    // Check allowedConnections
+    if (configuration.allowedConnections) {
+      configuration.allowedConnections.forEach((rule, index) => {
+        const basePath = `allowedConnections[${index}]`;
+        checkFields(rule as unknown as Record<string, unknown>, ALLOWED_FIELDS.connectionRule, basePath, configPath, violations);
+
+        if (rule.constraints) {
+          checkFields(
+            rule.constraints as Record<string, unknown>,
+            ALLOWED_FIELDS.connectionConstraints,
+            `${basePath}.constraints`,
+            configPath,
+            violations
+          );
+        }
+      });
+    }
+
+    // Check validation
+    if (configuration.validation) {
+      checkFields(
+        configuration.validation as Record<string, unknown>,
+        ALLOWED_FIELDS.validation,
+        'validation',
+        configPath,
+        violations
+      );
+
+      // Check state transitions
+      if (configuration.validation.stateTransitions) {
+        for (const [nodeType, transitions] of Object.entries(configuration.validation.stateTransitions)) {
+          if (Array.isArray(transitions)) {
+            transitions.forEach((transition, index) => {
+              checkFields(
+                transition as Record<string, unknown>,
+                ALLOWED_FIELDS.stateTransition,
+                `validation.stateTransitions.${nodeType}[${index}]`,
+                configPath,
+                violations
+              );
+            });
+          }
+        }
+      }
+
+      // Check constraints
+      if (configuration.validation.constraints && Array.isArray(configuration.validation.constraints)) {
+        configuration.validation.constraints.forEach((constraint, index) => {
+          checkFields(
+            constraint as Record<string, unknown>,
+            ALLOWED_FIELDS.constraint,
+            `validation.constraints[${index}]`,
+            configPath,
+            violations
+          );
+        });
+      }
+    }
+
+    // Check display
+    if (configuration.display) {
+      checkFields(
+        configuration.display as unknown as Record<string, unknown>,
+        ALLOWED_FIELDS.display,
+        'display',
+        configPath,
+        violations
+      );
+
+      if (configuration.display.theme) {
+        checkFields(
+          configuration.display.theme as Record<string, unknown>,
+          ALLOWED_FIELDS.displayTheme,
+          'display.theme',
+          configPath,
+          violations
+        );
+      }
+
+      if (configuration.display.animations) {
+        checkFields(
+          configuration.display.animations as Record<string, unknown>,
+          ALLOWED_FIELDS.displayAnimations,
+          'display.animations',
+          configPath,
+          violations
+        );
+      }
+    }
+
+    return violations;
+  },
+};
+
+/**
+ * Check an object's fields against allowed fields
+ */
+function checkFields(
+  obj: Record<string, unknown>,
+  allowedFields: string[],
+  path: string,
+  configPath: string | undefined,
+  violations: GraphRuleViolation[]
+): void {
+  for (const field of Object.keys(obj)) {
+    if (!allowedFields.includes(field)) {
+      const suggestion = findSimilarField(field, allowedFields);
+      violations.push({
+        ruleId: 'no-unknown-fields',
+        severity: 'error',
+        file: configPath,
+        path: path ? `${path}.${field}` : field,
+        message: `Unknown field "${field}"${path ? ` in ${path}` : ' at root level'}`,
+        impact: 'This field will be ignored and may indicate a configuration error',
+        suggestion: suggestion
+          ? `Did you mean "${suggestion}"? Allowed fields: ${allowedFields.join(', ')}`
+          : `Allowed fields: ${allowedFields.join(', ')}`,
+        fixable: true,
+        fixData: { path, field, suggestion },
+      });
+    }
+  }
+}
+
+/**
+ * Find a similar field name for "did you mean" suggestions
+ */
+function findSimilarField(field: string, allowedFields: string[]): string | null {
+  const fieldLower = field.toLowerCase();
+
+  for (const allowed of allowedFields) {
+    const allowedLower = allowed.toLowerCase();
+
+    // Check for substring match
+    if (fieldLower.includes(allowedLower) || allowedLower.includes(fieldLower)) {
+      return allowed;
+    }
+
+    // Check for small edit distance (typos)
+    if (Math.abs(field.length - allowed.length) <= 2) {
+      let differences = 0;
+      const minLen = Math.min(fieldLower.length, allowedLower.length);
+      for (let i = 0; i < minLen; i++) {
+        if (fieldLower[i] !== allowedLower[i]) differences++;
+      }
+      differences += Math.abs(field.length - allowed.length);
+      if (differences <= 2) return allowed;
+    }
+  }
+
+  return null;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Rule: orphaned-edge-types
+ * Warns when edgeTypes are not used in any connection rule
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const orphanedEdgeTypes: GraphRule = {
+  id: 'orphaned-edge-types',
+  name: 'Orphaned Edge Types',
+  description: 'EdgeTypes should be used in at least one connection rule',
+  impact: 'Orphaned edge types may indicate unused or misconfigured types',
+  severity: 'error',
+  category: 'structure',
+  enabled: true,
+  fixable: false,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    if (!configuration.edgeTypes || Object.keys(configuration.edgeTypes).length === 0) {
+      return violations;
+    }
+
+    // Collect all edgeTypes referenced in allowedConnections
+    const referencedEdgeTypes = new Set<string>();
+
+    if (configuration.allowedConnections) {
+      for (const connection of configuration.allowedConnections) {
+        if (connection.via) {
+          referencedEdgeTypes.add(connection.via);
+        }
+      }
+    }
+
+    // Check each edgeType
+    for (const typeId of Object.keys(configuration.edgeTypes)) {
+      if (!referencedEdgeTypes.has(typeId)) {
+        violations.push({
+          ruleId: 'orphaned-edge-types',
+          severity: 'error',
+          file: configPath,
+          path: `edgeTypes.${typeId}`,
+          message: `Edge type "${typeId}" is not used in any connection rule`,
+          impact: 'This edge type may be unused or misconfigured',
+          suggestion: `Add a connection rule using this edge type, or remove it if unused`,
+          fixable: false,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

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

@@ -0,0 +1,58 @@
+/**
+ * Rule: orphaned-node-types
+ * Warns when nodeTypes are not used in any connection rule
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const orphanedNodeTypes: GraphRule = {
+  id: 'orphaned-node-types',
+  name: 'Orphaned Node Types',
+  description: 'NodeTypes should be used in at least one connection rule',
+  impact: 'Orphaned node types may indicate unused or misconfigured types',
+  severity: 'error',
+  category: 'structure',
+  enabled: true,
+  fixable: false,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    if (!configuration.nodeTypes || Object.keys(configuration.nodeTypes).length === 0) {
+      return violations;
+    }
+
+    // Collect all nodeTypes referenced in allowedConnections
+    const referencedNodeTypes = new Set<string>();
+
+    if (configuration.allowedConnections) {
+      for (const connection of configuration.allowedConnections) {
+        if (connection.from) {
+          referencedNodeTypes.add(connection.from);
+        }
+        if (connection.to) {
+          referencedNodeTypes.add(connection.to);
+        }
+      }
+    }
+
+    // Check each nodeType
+    for (const typeId of Object.keys(configuration.nodeTypes)) {
+      if (!referencedNodeTypes.has(typeId)) {
+        violations.push({
+          ruleId: 'orphaned-node-types',
+          severity: 'error',
+          file: configPath,
+          path: `nodeTypes.${typeId}`,
+          message: `Node type "${typeId}" is not used in any connection rule`,
+          impact: 'This node type may be unused or misconfigured',
+          suggestion: `Add a connection rule using this node type, or remove it if unused`,
+          fixable: false,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/rules/implementations/required-metadata.ts

@@ -0,0 +1,64 @@
+/**
+ * Rule: required-metadata
+ * Ensures configuration has required metadata fields (name, version)
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const requiredMetadata: GraphRule = {
+  id: 'required-metadata',
+  name: 'Required Metadata',
+  description: 'Configuration must have name and version in metadata',
+  impact: 'Missing metadata makes configurations hard to identify and version',
+  severity: 'error',
+  category: 'schema',
+  enabled: true,
+  fixable: false,
+
+  async check(context: GraphRuleContext): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath } = context;
+
+    if (!configuration.metadata) {
+      violations.push({
+        ruleId: 'required-metadata',
+        severity: 'error',
+        file: configPath,
+        path: 'metadata',
+        message: 'Configuration is missing metadata section',
+        impact: 'Cannot identify or version this configuration',
+        suggestion: 'Add a metadata section with name and version fields',
+        fixable: false,
+      });
+      return violations;
+    }
+
+    if (!configuration.metadata.name) {
+      violations.push({
+        ruleId: 'required-metadata',
+        severity: 'error',
+        file: configPath,
+        path: 'metadata.name',
+        message: 'Configuration metadata is missing required "name" field',
+        impact: 'Cannot identify this configuration',
+        suggestion: 'Add a name field to metadata',
+        fixable: false,
+      });
+    }
+
+    if (!configuration.metadata.version) {
+      violations.push({
+        ruleId: 'required-metadata',
+        severity: 'error',
+        file: configPath,
+        path: 'metadata.version',
+        message: 'Configuration metadata is missing required "version" field',
+        impact: 'Cannot track configuration versions',
+        suggestion: 'Add a version field (e.g., "1.0.0") to metadata',
+        fixable: false,
+      });
+    }
+
+    return violations;
+  },
+};

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

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