@principal-ai/principal-view-core 0.5.6

package/src/rules/implementations/connection-type-references.ts

@@ -0,0 +1,117 @@
+/**
+ * Rule: connection-type-references
+ * Ensures allowedConnections only reference existing nodeTypes and edgeTypes
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation } from '../types';
+
+export const connectionTypeReferences: GraphRule = {
+  id: 'connection-type-references',
+  name: 'Connection Type References',
+  description: 'allowedConnections must reference existing nodeTypes and edgeTypes',
+  impact: 'Invalid references will cause connection 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.allowedConnections || configuration.allowedConnections.length === 0) {
+      return violations;
+    }
+
+    // Get defined node and edge types
+    const nodeTypeIds = new Set(Object.keys(configuration.nodeTypes ?? {}));
+    const edgeTypeIds = new Set(Object.keys(configuration.edgeTypes ?? {}));
+
+    for (let i = 0; i < configuration.allowedConnections.length; i++) {
+      const connection = configuration.allowedConnections[i];
+      const basePath = `allowedConnections[${i}]`;
+
+      // Check 'from' references a valid nodeType
+      if (connection.from && !nodeTypeIds.has(connection.from)) {
+        const suggestion = findSimilar(connection.from, nodeTypeIds);
+        violations.push({
+          ruleId: 'connection-type-references',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.from`,
+          message: `Connection rule references undefined nodeType "${connection.from}"`,
+          impact: 'This connection rule will not match any nodes',
+          suggestion: suggestion
+            ? `Did you mean "${suggestion}"?`
+            : `Available nodeTypes: ${[...nodeTypeIds].join(', ') || '(none defined)'}`,
+          fixable: false,
+        });
+      }
+
+      // Check 'to' references a valid nodeType
+      if (connection.to && !nodeTypeIds.has(connection.to)) {
+        const suggestion = findSimilar(connection.to, nodeTypeIds);
+        violations.push({
+          ruleId: 'connection-type-references',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.to`,
+          message: `Connection rule references undefined nodeType "${connection.to}"`,
+          impact: 'This connection rule will not match any nodes',
+          suggestion: suggestion
+            ? `Did you mean "${suggestion}"?`
+            : `Available nodeTypes: ${[...nodeTypeIds].join(', ') || '(none defined)'}`,
+          fixable: false,
+        });
+      }
+
+      // Check 'via' references a valid edgeType
+      if (connection.via && !edgeTypeIds.has(connection.via)) {
+        const suggestion = findSimilar(connection.via, edgeTypeIds);
+        violations.push({
+          ruleId: 'connection-type-references',
+          severity: 'error',
+          file: configPath,
+          path: `${basePath}.via`,
+          message: `Connection rule references undefined edgeType "${connection.via}"`,
+          impact: 'This connection rule will not match any edges',
+          suggestion: suggestion
+            ? `Did you mean "${suggestion}"?`
+            : `Available edgeTypes: ${[...edgeTypeIds].join(', ') || '(none defined)'}`,
+          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/dead-end-states.ts

@@ -0,0 +1,101 @@
+/**
+ * Rule: dead-end-states
+ * Warns when states have no exit transitions (except terminal states)
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
+
+/**
+ * Options for dead-end-states rule
+ */
+export interface DeadEndStatesOptions extends RuleOptions {
+  /**
+   * States that are intentionally terminal (no exits expected)
+   * @default ["completed", "failed", "terminated", "done", "error", "finished", "end"]
+   */
+  terminalStates: string[];
+}
+
+const DEFAULT_OPTIONS: DeadEndStatesOptions = {
+  terminalStates: ['completed', 'failed', 'terminated', 'done', 'error', 'finished', 'end'],
+};
+
+export const deadEndStates: GraphRule<DeadEndStatesOptions> = {
+  id: 'dead-end-states',
+  name: 'Dead End States',
+  description: 'States should have exit transitions unless they are terminal states',
+  impact: 'Dead-end states may trap entities unexpectedly',
+  severity: 'error',
+  category: 'structure',
+  enabled: true,
+  fixable: false,
+  defaultOptions: DEFAULT_OPTIONS,
+
+  async check(context: GraphRuleContext<DeadEndStatesOptions>): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath, options } = context;
+
+    const terminalStates = new Set(
+      (options.terminalStates ?? DEFAULT_OPTIONS.terminalStates).map((s) => s.toLowerCase())
+    );
+
+    if (!configuration.nodeTypes) {
+      return violations;
+    }
+
+    // For each nodeType with states, check if all non-terminal states have exits
+    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, no transitions expected
+      if (stateIds.length <= 1) {
+        continue;
+      }
+
+      // Get state transitions for this nodeType
+      const transitions = configuration.validation?.stateTransitions?.[typeId];
+
+      // Build set of states that have exit transitions
+      const statesWithExits = new Set<string>();
+
+      if (transitions && Array.isArray(transitions)) {
+        for (const transition of transitions) {
+          if (transition.from) {
+            statesWithExits.add(transition.from);
+          }
+        }
+      }
+
+      // Check for dead-end states
+      for (const stateId of stateIds) {
+        // Skip if this state has exits
+        if (statesWithExits.has(stateId)) {
+          continue;
+        }
+
+        // Skip if this is a known terminal state
+        if (terminalStates.has(stateId.toLowerCase())) {
+          continue;
+        }
+
+        // This is a dead-end state
+        violations.push({
+          ruleId: 'dead-end-states',
+          severity: 'error',
+          file: configPath,
+          path: `nodeTypes.${typeId}.states.${stateId}`,
+          message: `State "${stateId}" in node type "${typeId}" has no exit transitions`,
+          impact: 'Entities in this state cannot transition to other states',
+          suggestion: `Add a transition from "${stateId}" in validation.stateTransitions.${typeId}, or mark it as a terminal state`,
+          fixable: false,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/rules/implementations/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Built-in rule implementations
+ */
+
+// Schema rules
+export { requiredMetadata } from './required-metadata';
+export { validNodeTypes } from './valid-node-types';
+export { validEdgeTypes } from './valid-edge-types';
+export { validColorFormat } from './valid-color-format';
+export { noUnknownFields } from './no-unknown-fields';
+
+// Reference rules
+export { connectionTypeReferences } from './connection-type-references';
+export { stateTransitionReferences } from './state-transition-references';
+
+// Structure rules
+export { minimumNodeSources, type MinimumNodeSourcesOptions } from './minimum-node-sources';
+export { orphanedNodeTypes } from './orphaned-node-types';
+export { orphanedEdgeTypes } from './orphaned-edge-types';
+export { unreachableStates } from './unreachable-states';
+export { deadEndStates, type DeadEndStatesOptions } from './dead-end-states';
+
+// Pattern rules
+export { validActionPatterns, type ValidActionPatternsOptions } from './valid-action-patterns';
+
+// Library rules
+export { libraryNodeTypeMatch, type LibraryNodeTypeMatchOptions } from './library-node-type-match';
+
+import type { GraphRule } from '../types';
+import { requiredMetadata } from './required-metadata';
+import { validNodeTypes } from './valid-node-types';
+import { validEdgeTypes } from './valid-edge-types';
+import { validColorFormat } from './valid-color-format';
+import { noUnknownFields } from './no-unknown-fields';
+import { connectionTypeReferences } from './connection-type-references';
+import { stateTransitionReferences } from './state-transition-references';
+import { minimumNodeSources } from './minimum-node-sources';
+import { orphanedNodeTypes } from './orphaned-node-types';
+import { orphanedEdgeTypes } from './orphaned-edge-types';
+import { unreachableStates } from './unreachable-states';
+import { deadEndStates } from './dead-end-states';
+import { validActionPatterns } from './valid-action-patterns';
+import { libraryNodeTypeMatch } from './library-node-type-match';
+
+/**
+ * All built-in rules
+ * Cast to GraphRule[] since rules with specific options extend the base interface
+ */
+export const builtinRules: GraphRule[] = [
+  // Schema rules (5)
+  noUnknownFields,
+  requiredMetadata,
+  validNodeTypes,
+  validEdgeTypes,
+  validColorFormat,
+
+  // Reference rules (2)
+  connectionTypeReferences,
+  stateTransitionReferences,
+
+  // Structure rules (5)
+  minimumNodeSources as unknown as GraphRule,
+  orphanedNodeTypes,
+  orphanedEdgeTypes,
+  unreachableStates,
+  deadEndStates as unknown as GraphRule,
+
+  // Pattern rules (1)
+  validActionPatterns as unknown as GraphRule,
+
+  // Library rules (1)
+  libraryNodeTypeMatch as unknown as GraphRule,
+];

package/src/rules/implementations/library-node-type-match.ts

@@ -0,0 +1,148 @@
+/**
+ * Rule: library-node-type-match
+ * Ensures nodeTypes match library nodeComponents when a library is provided
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
+
+/**
+ * Options for library-node-type-match rule
+ */
+export interface LibraryNodeTypeMatchOptions extends RuleOptions {
+  /**
+   * Allow extra nodeTypes not defined in the library
+   * @default false
+   */
+  allowExtra: boolean;
+}
+
+const DEFAULT_OPTIONS: LibraryNodeTypeMatchOptions = {
+  allowExtra: false,
+};
+
+export const libraryNodeTypeMatch: GraphRule<LibraryNodeTypeMatchOptions> = {
+  id: 'library-node-type-match',
+  name: 'Library Node Type Match',
+  description: 'NodeTypes must match library nodeComponents when a library is provided',
+  impact: 'Mismatched types may cause inconsistent behavior or missing features',
+  severity: 'error',
+  category: 'library',
+  enabled: true,
+  fixable: false,
+  defaultOptions: DEFAULT_OPTIONS,
+
+  async check(context: GraphRuleContext<LibraryNodeTypeMatchOptions>): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, library, configPath, libraryPath, options } = context;
+
+    // Skip if no library is provided
+    if (!library) {
+      return violations;
+    }
+
+    // Skip if library has no nodeComponents
+    if (!library.nodeComponents || Object.keys(library.nodeComponents).length === 0) {
+      return violations;
+    }
+
+    const libraryNodeTypes = new Set(Object.keys(library.nodeComponents));
+    const configNodeTypes = Object.keys(configuration.nodeTypes ?? {});
+
+    // Check each nodeType in configuration
+    for (const typeId of configNodeTypes) {
+      if (!libraryNodeTypes.has(typeId)) {
+        if (!options.allowExtra) {
+          const suggestion = findSimilar(typeId, libraryNodeTypes);
+          violations.push({
+            ruleId: 'library-node-type-match',
+            severity: 'error',
+            file: configPath,
+            path: `nodeTypes.${typeId}`,
+            message: `Node type "${typeId}" is not defined in the component library`,
+            impact: 'This node type may be missing library-defined behavior or styling',
+            suggestion: suggestion
+              ? `Did you mean "${suggestion}"?`
+              : `Available library nodeComponents: ${[...libraryNodeTypes].join(', ')}`,
+            fixable: false,
+          });
+        }
+      } else {
+        // Validate that config matches library definition
+        const libraryComponent = library.nodeComponents[typeId];
+        const configNodeType = configuration.nodeTypes![typeId];
+
+        // Check shape matches if library defines one
+        if (libraryComponent.shape && configNodeType.shape !== libraryComponent.shape) {
+          violations.push({
+            ruleId: 'library-node-type-match',
+            severity: 'error',
+            file: configPath,
+            path: `nodeTypes.${typeId}.shape`,
+            message: `Node type "${typeId}" shape "${configNodeType.shape}" doesn't match library definition "${libraryComponent.shape}"`,
+            impact: 'Node may render differently than expected',
+            suggestion: `Use shape "${libraryComponent.shape}" as defined in the library`,
+            fixable: true,
+            fixData: {
+              typeId,
+              field: 'shape',
+              expected: libraryComponent.shape,
+              actual: configNodeType.shape,
+            },
+          });
+        }
+
+        // Check that config defines all states from library
+        if (libraryComponent.states && Object.keys(libraryComponent.states).length > 0) {
+          const libraryStates = Object.keys(libraryComponent.states);
+          const configStates = configNodeType.states ? Object.keys(configNodeType.states) : [];
+
+          for (const stateId of libraryStates) {
+            if (!configStates.includes(stateId)) {
+              violations.push({
+                ruleId: 'library-node-type-match',
+                severity: 'error',
+                file: configPath,
+                path: `nodeTypes.${typeId}.states`,
+                message: `Node type "${typeId}" is missing state "${stateId}" defined in library`,
+                impact: 'State transitions to this state may fail',
+                suggestion: `Add state "${stateId}" to nodeTypes.${typeId}.states`,
+                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/minimum-node-sources.ts

@@ -0,0 +1,82 @@
+/**
+ * Rule: minimum-node-sources
+ * Ensures each nodeType has at least a minimum number of sources defined
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
+
+/**
+ * Options for minimum-node-sources rule
+ */
+export interface MinimumNodeSourcesOptions extends RuleOptions {
+  /**
+   * Minimum number of sources required per nodeType
+   * @default 1
+   */
+  minimum: number;
+
+  /**
+   * NodeType IDs to exclude from this check
+   * @default []
+   */
+  excludeNodeTypes: string[];
+}
+
+const DEFAULT_OPTIONS: MinimumNodeSourcesOptions = {
+  minimum: 1,
+  excludeNodeTypes: [],
+};
+
+export const minimumNodeSources: GraphRule<MinimumNodeSourcesOptions> = {
+  id: 'minimum-node-sources',
+  name: 'Minimum Node Sources',
+  description: 'Each nodeType must have at least a minimum number of sources defined',
+  impact: 'NodeTypes without sources cannot be associated with log activity',
+  severity: 'error',
+  category: 'structure',
+  enabled: true,
+  fixable: false,
+  defaultOptions: DEFAULT_OPTIONS,
+
+  async check(context: GraphRuleContext<MinimumNodeSourcesOptions>): Promise<GraphRuleViolation[]> {
+    const violations: GraphRuleViolation[] = [];
+    const { configuration, configPath, options } = context;
+
+    const minimum = options.minimum ?? DEFAULT_OPTIONS.minimum;
+    const excludeNodeTypes = options.excludeNodeTypes ?? DEFAULT_OPTIONS.excludeNodeTypes;
+
+    if (!configuration.nodeTypes) {
+      return violations;
+    }
+
+    for (const [typeId, nodeType] of Object.entries(configuration.nodeTypes)) {
+      // Skip excluded node types
+      if (excludeNodeTypes.includes(typeId)) {
+        continue;
+      }
+
+      // Get sources from nodeType (may be extended via path-based config)
+      const nodeTypeAny = nodeType as unknown as Record<string, unknown>;
+      const sources = nodeTypeAny.sources;
+      const sourceCount = Array.isArray(sources) ? sources.length : 0;
+
+      if (sourceCount < minimum) {
+        violations.push({
+          ruleId: 'minimum-node-sources',
+          severity: 'error',
+          file: configPath,
+          path: `nodeTypes.${typeId}.sources`,
+          message:
+            sourceCount === 0
+              ? `Node type "${typeId}" has no sources defined`
+              : `Node type "${typeId}" has ${sourceCount} source(s), minimum required is ${minimum}`,
+          impact: 'This node type cannot be associated with log activity from source files',
+          suggestion: `Add at least ${minimum} source path(s) to nodeTypes.${typeId}.sources`,
+          fixable: false,
+        });
+      }
+    }
+
+    return violations;
+  },
+};