@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/rules/implementations/index.ts

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

@@ -1,84 +0,0 @@
-/**
- * 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

@@ -1,372 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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

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