@plures/praxis 0.2.0

package/src/core/protocol.ts

@@ -0,0 +1,132 @@
+/**
+ * Core Praxis Protocol
+ * 
+ * Language-neutral, JSON-friendly protocol that forms the foundation of Praxis.
+ * This protocol is designed to be stable and portable across languages (TypeScript, C#, PowerShell, etc.)
+ * 
+ * The protocol defines the conceptual core of the engine:
+ * - Pure, deterministic, data in → data out
+ * - No side effects, no global state
+ * - All higher-level TypeScript APIs are built on top of this protocol
+ * 
+ * ## Protocol Versioning
+ * 
+ * The Praxis protocol follows semantic versioning (MAJOR.MINOR.PATCH):
+ * - MAJOR: Breaking changes to core protocol types or semantics
+ * - MINOR: Backward-compatible additions to protocol (new optional fields)
+ * - PATCH: Clarifications, documentation updates, no functional changes
+ * 
+ * Current version: 1.0.0
+ * 
+ * ### Stability Guarantees
+ * 
+ * 1. **Core Types Stability**: The following types are considered stable and will not
+ *    change in backward-incompatible ways within the same major version:
+ *    - PraxisFact (tag, payload structure)
+ *    - PraxisEvent (tag, payload structure)
+ *    - PraxisState (context, facts, meta structure)
+ *    - PraxisStepFn signature
+ * 
+ * 2. **JSON Compatibility**: All protocol types will remain JSON-serializable.
+ *    No non-JSON-safe types (functions, symbols, etc.) will be added to the protocol.
+ * 
+ * 3. **Cross-Language Compatibility**: Protocol changes will be coordinated across
+ *    all official language implementations (TypeScript, C#, PowerShell) to ensure
+ *    interoperability.
+ * 
+ * 4. **Migration Path**: Major version changes will be accompanied by:
+ *    - Migration guide
+ *    - Deprecation warnings in previous version
+ *    - Compatibility shims where possible
+ */
+
+/**
+ * Protocol version following semantic versioning
+ */
+export const PRAXIS_PROTOCOL_VERSION = "1.0.0" as const;
+
+/**
+ * A fact is a typed proposition about the domain.
+ * Examples: UserLoggedIn, CartItem, NetworkOnline
+ */
+export interface PraxisFact {
+  /** Tag identifying the fact type */
+  tag: string;
+  /** Payload containing the fact data */
+  payload: unknown;
+}
+
+/**
+ * An event is a temporally ordered fact meant to drive change.
+ * Examples: LOGIN, LOGOUT, ADD_TO_CART
+ */
+export interface PraxisEvent {
+  /** Tag identifying the event type */
+  tag: string;
+  /** Payload containing the event data */
+  payload: unknown;
+}
+
+/**
+ * The state of the Praxis engine at a point in time.
+ */
+export interface PraxisState {
+  /** Application context (domain-specific data) */
+  context: unknown;
+  /** Current facts about the domain */
+  facts: PraxisFact[];
+  /** Optional metadata (timestamps, version, etc.) */
+  meta?: Record<string, unknown>;
+  /** Protocol version (for cross-language compatibility) */
+  protocolVersion?: string;
+}
+
+/**
+ * Diagnostic information about constraint violations or rule errors.
+ */
+export interface PraxisDiagnostics {
+  /** Kind of diagnostic */
+  kind: "constraint-violation" | "rule-error";
+  /** Human-readable message */
+  message: string;
+  /** Additional diagnostic data */
+  data?: unknown;
+}
+
+/**
+ * Configuration for a step execution.
+ * Specifies which rules and constraints to apply.
+ */
+export interface PraxisStepConfig {
+  /** IDs of rules to apply during this step */
+  ruleIds: string[];
+  /** IDs of constraints to check during this step */
+  constraintIds: string[];
+}
+
+/**
+ * Result of a step execution.
+ */
+export interface PraxisStepResult {
+  /** New state after applying rules and checking constraints */
+  state: PraxisState;
+  /** Diagnostics from rule execution and constraint checking */
+  diagnostics: PraxisDiagnostics[];
+}
+
+/**
+ * The core step function of the Praxis engine.
+ * 
+ * This is the conceptual heart of the engine:
+ * - Takes current state, events, and configuration
+ * - Applies rules and checks constraints
+ * - Returns new state and diagnostics
+ * 
+ * Pure, deterministic, data in → data out.
+ * No side effects, no global state.
+ */
+export type PraxisStepFn = (
+  state: PraxisState,
+  events: PraxisEvent[],
+  config: PraxisStepConfig
+) => PraxisStepResult;

package/src/core/rules.ts

@@ -0,0 +1,167 @@
+/**
+ * Rules and Constraints System
+ * 
+ * This module defines the types and registry for rules and constraints.
+ * Rules and constraints are identified by stable IDs and can be described as data,
+ * making them portable across languages and suitable for DSL-based definitions.
+ */
+
+import type { PraxisEvent, PraxisFact, PraxisState } from "./protocol.js";
+
+/**
+ * Unique identifier for a rule
+ */
+export type RuleId = string;
+
+/**
+ * Unique identifier for a constraint
+ */
+export type ConstraintId = string;
+
+/**
+ * A rule function derives new facts or transitions from context + input facts/events.
+ * Rules must be pure - no side effects.
+ * 
+ * @param state Current Praxis state
+ * @param events Events to process
+ * @returns Array of new facts to add to the state
+ */
+export type RuleFn<TContext = unknown> = (
+  state: PraxisState & { context: TContext },
+  events: PraxisEvent[]
+) => PraxisFact[];
+
+/**
+ * A constraint function checks that an invariant holds.
+ * Constraints must be pure - no side effects.
+ * 
+ * @param state Current Praxis state
+ * @returns true if constraint is satisfied, false or error message if violated
+ */
+export type ConstraintFn<TContext = unknown> = (
+  state: PraxisState & { context: TContext }
+) => boolean | string;
+
+/**
+ * Descriptor for a rule, including its ID, description, and implementation.
+ */
+export interface RuleDescriptor<TContext = unknown> {
+  /** Unique identifier for the rule */
+  id: RuleId;
+  /** Human-readable description */
+  description: string;
+  /** Implementation function */
+  impl: RuleFn<TContext>;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Descriptor for a constraint, including its ID, description, and implementation.
+ */
+export interface ConstraintDescriptor<TContext = unknown> {
+  /** Unique identifier for the constraint */
+  id: ConstraintId;
+  /** Human-readable description */
+  description: string;
+  /** Implementation function */
+  impl: ConstraintFn<TContext>;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * A Praxis module bundles rules and constraints.
+ * Modules can be composed and registered with the engine.
+ */
+export interface PraxisModule<TContext = unknown> {
+  /** Rules in this module */
+  rules: RuleDescriptor<TContext>[];
+  /** Constraints in this module */
+  constraints: ConstraintDescriptor<TContext>[];
+  /** Optional module metadata */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Registry for rules and constraints.
+ * Maps IDs to their descriptors.
+ */
+export class PraxisRegistry<TContext = unknown> {
+  private rules = new Map<RuleId, RuleDescriptor<TContext>>();
+  private constraints = new Map<ConstraintId, ConstraintDescriptor<TContext>>();
+
+  /**
+   * Register a rule
+   */
+  registerRule(descriptor: RuleDescriptor<TContext>): void {
+    if (this.rules.has(descriptor.id)) {
+      throw new Error(`Rule with id "${descriptor.id}" already registered`);
+    }
+    this.rules.set(descriptor.id, descriptor);
+  }
+
+  /**
+   * Register a constraint
+   */
+  registerConstraint(descriptor: ConstraintDescriptor<TContext>): void {
+    if (this.constraints.has(descriptor.id)) {
+      throw new Error(`Constraint with id "${descriptor.id}" already registered`);
+    }
+    this.constraints.set(descriptor.id, descriptor);
+  }
+
+  /**
+   * Register a module (all its rules and constraints)
+   */
+  registerModule(module: PraxisModule<TContext>): void {
+    for (const rule of module.rules) {
+      this.registerRule(rule);
+    }
+    for (const constraint of module.constraints) {
+      this.registerConstraint(constraint);
+    }
+  }
+
+  /**
+   * Get a rule by ID
+   */
+  getRule(id: RuleId): RuleDescriptor<TContext> | undefined {
+    return this.rules.get(id);
+  }
+
+  /**
+   * Get a constraint by ID
+   */
+  getConstraint(id: ConstraintId): ConstraintDescriptor<TContext> | undefined {
+    return this.constraints.get(id);
+  }
+
+  /**
+   * Get all registered rule IDs
+   */
+  getRuleIds(): RuleId[] {
+    return Array.from(this.rules.keys());
+  }
+
+  /**
+   * Get all registered constraint IDs
+   */
+  getConstraintIds(): ConstraintId[] {
+    return Array.from(this.constraints.keys());
+  }
+
+  /**
+   * Get all rules
+   */
+  getAllRules(): RuleDescriptor<TContext>[] {
+    return Array.from(this.rules.values());
+  }
+
+  /**
+   * Get all constraints
+   */
+  getAllConstraints(): ConstraintDescriptor<TContext>[] {
+    return Array.from(this.constraints.values());
+  }
+}

package/src/core/schema/loader.ts

@@ -0,0 +1,247 @@
+/**
+ * Praxis Schema Loader
+ * 
+ * Loads and validates Praxis schema files.
+ */
+
+import { readFile } from 'fs/promises';
+import { pathToFileURL } from 'url';
+import { load as yamlLoad } from 'js-yaml';
+import type { PraxisSchema, ValidationResult } from './types.js';
+import { validateSchema } from './types.js';
+
+/**
+ * Loader options
+ */
+export interface LoaderOptions {
+  /** Validate schema after loading */
+  validate?: boolean;
+  /** Base directory for resolving relative paths */
+  baseDir?: string;
+}
+
+/**
+ * Loader result
+ */
+export interface LoaderResult {
+  /** Loaded schema */
+  schema?: PraxisSchema;
+  /** Validation result */
+  validation?: ValidationResult;
+  /** Load errors */
+  errors: string[];
+}
+
+/**
+ * Load a Praxis schema from a file
+ */
+export async function loadSchema(
+  filePath: string,
+  options: LoaderOptions = {}
+): Promise<LoaderResult> {
+  const errors: string[] = [];
+  
+  try {
+    // Only .js files are supported. TypeScript schema files must be compiled to .js first.
+    // Use a compiled JavaScript file for your schema.
+    // Dynamic import is used, which works with .js files only.
+    
+    // Convert to absolute URL for ES module import
+    let fileUrl = pathToFileURL(filePath).href;
+    
+    // Attempt to import .ts or .js files directly. If import fails, error will be caught below.
+    
+    // Dynamic import of the schema file
+    const module = await import(fileUrl);
+    
+    // Look for common schema export names
+    let schema: PraxisSchema | undefined;
+    if (module.default) {
+      schema = module.default;
+    } else if (module.schema) {
+      schema = module.schema;
+    } else if (module.appSchema) {
+      schema = module.appSchema;
+    } else {
+      // Try to find any object that looks like a PraxisSchema
+      const exports = Object.values(module);
+      const possibleSchema = exports.find(
+        (exp): exp is PraxisSchema =>
+          typeof exp === 'object' &&
+          exp !== null &&
+          'version' in exp &&
+          'name' in exp
+      );
+      if (possibleSchema) {
+        schema = possibleSchema;
+      }
+    }
+    
+    if (!schema) {
+      errors.push(
+        'Schema file must export a PraxisSchema object (as default, schema, or appSchema)'
+      );
+      return { errors };
+    }
+    
+    // Validate if requested
+    let validation: ValidationResult | undefined;
+    if (options.validate !== false) {
+      validation = validateSchema(schema);
+      if (!validation.valid) {
+        errors.push('Schema validation failed:');
+        validation.errors.forEach((error) => {
+          errors.push(`  ${error.path}: ${error.message}`);
+        });
+      }
+    }
+    
+    return {
+      schema,
+      validation,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(`Failed to load schema: ${error.message}`);
+    } else {
+      errors.push('Failed to load schema: Unknown error');
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Load schema from JSON string
+ */
+export function loadSchemaFromJson(
+  json: string,
+  options: LoaderOptions = {}
+): LoaderResult {
+  const errors: string[] = [];
+  
+  try {
+    const schema = JSON.parse(json) as PraxisSchema;
+    
+    // Validate if requested
+    let validation: ValidationResult | undefined;
+    if (options.validate !== false) {
+      validation = validateSchema(schema);
+      if (!validation.valid) {
+        errors.push('Schema validation failed:');
+        validation.errors.forEach((error) => {
+          errors.push(`  ${error.path}: ${error.message}`);
+        });
+      }
+    }
+    
+    return {
+      schema,
+      validation,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(`Failed to parse JSON: ${error.message}`);
+    } else {
+      errors.push('Failed to parse JSON: Unknown error');
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Load schema from YAML string
+ */
+export function loadSchemaFromYaml(
+  yaml: string,
+  options: LoaderOptions = {}
+): LoaderResult {
+  const errors: string[] = [];
+  
+  try {
+    const schema = yamlLoad(yaml) as PraxisSchema;
+    
+    // Validate if requested
+    let validation: ValidationResult | undefined;
+    if (options.validate !== false) {
+      validation = validateSchema(schema);
+      if (!validation.valid) {
+        errors.push('Schema validation failed:');
+        validation.errors.forEach((error) => {
+          errors.push(`  ${error.path}: ${error.message}`);
+        });
+      }
+    }
+    
+    return {
+      schema,
+      validation,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(`Failed to parse YAML: ${error.message}`);
+    } else {
+      errors.push('Failed to parse YAML: Unknown error');
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Load schema from file (supports .ts, .json, and .yaml/.yml)
+ */
+export async function loadSchemaFromFile(
+  filePath: string,
+  options: LoaderOptions = {}
+): Promise<LoaderResult> {
+  if (filePath.endsWith('.json')) {
+    const content = await readFile(filePath, 'utf-8');
+    return loadSchemaFromJson(content, options);
+  } else if (filePath.endsWith('.yaml') || filePath.endsWith('.yml')) {
+    const content = await readFile(filePath, 'utf-8');
+    return loadSchemaFromYaml(content, options);
+  } else {
+    return loadSchema(filePath, options);
+  }
+}
+
+/**
+ * Validate that a loaded schema has required fields for generation
+ */
+export function validateForGeneration(schema: PraxisSchema): ValidationResult {
+  const errors: string[] = [];
+  
+  // Check for entities/models
+  if (!schema.models || schema.models.length === 0) {
+    errors.push('Schema must define at least one model for generation');
+  }
+  
+  // Check that models have valid fields
+  schema.models?.forEach((model, index) => {
+    if (!model.fields || model.fields.length === 0) {
+      errors.push(
+        `Model "${model.name}" at index ${index} must have at least one field`
+      );
+    }
+    
+    model.fields?.forEach((field, fieldIndex) => {
+      if (!field.name) {
+        errors.push(
+          `Field at index ${fieldIndex} in model "${model.name}" must have a name`
+        );
+      }
+      if (!field.type) {
+        errors.push(
+          `Field "${field.name}" in model "${model.name}" must have a type`
+        );
+      }
+    });
+  });
+  
+  return {
+    valid: errors.length === 0,
+    errors: errors.map((message) => ({ path: 'schema', message })),
+  };
+}