@principal-ai/subsystems-core 0.29.0

package/src/rules/implementations/index.ts

@@ -0,0 +1,66 @@
+/**
+ * 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';
+
+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';
+
+/**
+ * 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,
+];

package/src/rules/implementations/minimum-node-sources.ts

@@ -0,0 +1,84 @@
+/**
+ * Rule: minimum-node-sources
+ * Ensures each nodeType has at least a minimum number of references (or sources) defined
+ *
+ * Note: This rule checks `references` field, with fallback to deprecated `sources` field.
+ */
+
+import type { GraphRule, GraphRuleContext, GraphRuleViolation, RuleOptions } from '../types';
+
+/**
+ * Options for minimum-node-sources rule
+ */
+export interface MinimumNodeSourcesOptions extends RuleOptions {
+  /**
+   * Minimum number of references 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 References',
+  description: 'Each nodeType must have at least a minimum number of references defined',
+  impact: 'NodeTypes without references 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 references from nodeType, with fallback to deprecated sources
+      const nodeTypeAny = nodeType as unknown as Record<string, unknown>;
+      const refs = nodeTypeAny.references ?? nodeTypeAny.sources;
+      const refCount = Array.isArray(refs) ? refs.length : 0;
+
+      if (refCount < minimum) {
+        violations.push({
+          ruleId: 'minimum-node-sources',
+          severity: 'error',
+          file: configPath,
+          path: `nodeTypes.${typeId}.references`,
+          message:
+            refCount === 0
+              ? `Node type "${typeId}" has no references defined`
+              : `Node type "${typeId}" has ${refCount} reference(s), minimum required is ${minimum}`,
+          impact: 'This node type cannot be associated with log activity from source files',
+          suggestion: `Add at least ${minimum} reference path(s) to nodeTypes.${typeId}.references`,
+          fixable: false,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

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

@@ -0,0 +1,372 @@
+/**
+ * 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: [
+    'description',
+    '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', 'description', 'placeholder'],
+  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,52 @@
+/**
+ * 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,
+      });
+    }
+
+
+    return violations;
+  },
+};