@plures/praxis 1.1.2 → 1.2.0

package/dist/node/chunk-S54337I5.js

@@ -0,0 +1,446 @@
+// src/integrations/state-docs.ts
+var StateDocsGenerator = class {
+  config;
+  constructor(config) {
+    this.config = {
+      target: "./docs",
+      globs: ["**/*.ts", "**/*.js"],
+      visualization: {
+        format: "mermaid",
+        exportPng: false,
+        theme: "default"
+      },
+      template: {
+        toc: true,
+        timestamp: true
+      },
+      ...config
+    };
+  }
+  /**
+   * Generate documentation from a Praxis schema
+   */
+  generateFromSchema(schema) {
+    const docs = [];
+    docs.push(this.generateSchemaReadme(schema));
+    if (schema.models && schema.models.length > 0) {
+      docs.push(this.generateModelsDoc(schema));
+    }
+    if (schema.components && schema.components.length > 0) {
+      docs.push(this.generateComponentsDoc(schema));
+    }
+    if (schema.logic && schema.logic.length > 0) {
+      for (const logic of schema.logic) {
+        docs.push(this.generateLogicDoc(logic));
+        docs.push(this.generateLogicDiagram(logic));
+      }
+    }
+    return docs;
+  }
+  /**
+   * Generate documentation from a Praxis registry
+   */
+  generateFromModule(module) {
+    const docs = [];
+    const rules = module.rules;
+    const constraints = module.constraints;
+    docs.push(this.generateRulesDoc(rules));
+    docs.push(this.generateConstraintsDoc(constraints));
+    docs.push(this.generateRegistryDiagram(rules, constraints));
+    return docs;
+  }
+  /**
+   * Generate the main schema README
+   */
+  generateSchemaReadme(schema) {
+    const lines = [];
+    if (this.config.template?.header) {
+      lines.push(this.config.template.header);
+      lines.push("");
+    }
+    lines.push(`# ${schema.name || this.config.projectTitle}`);
+    lines.push("");
+    if (schema.description) {
+      lines.push(schema.description);
+      lines.push("");
+    }
+    if (this.config.template?.toc) {
+      lines.push("## Table of Contents");
+      lines.push("");
+      lines.push("- [Overview](#overview)");
+      if (schema.models && schema.models.length > 0) {
+        lines.push("- [Models](#models)");
+      }
+      if (schema.components && schema.components.length > 0) {
+        lines.push("- [Components](#components)");
+      }
+      if (schema.logic && schema.logic.length > 0) {
+        lines.push("- [Logic](#logic)");
+      }
+      lines.push("");
+    }
+    lines.push("## Overview");
+    lines.push("");
+    lines.push(`**Version:** ${schema.version}`);
+    lines.push("");
+    lines.push("### Statistics");
+    lines.push("");
+    lines.push("| Category | Count |");
+    lines.push("|----------|-------|");
+    lines.push(`| Models | ${schema.models?.length || 0} |`);
+    lines.push(`| Components | ${schema.components?.length || 0} |`);
+    lines.push(`| Logic Modules | ${schema.logic?.length || 0} |`);
+    lines.push("");
+    if (schema.models && schema.models.length > 0) {
+      lines.push("## Models");
+      lines.push("");
+      for (const model of schema.models) {
+        lines.push(`### ${model.name}`);
+        lines.push("");
+        if (model.description) {
+          lines.push(model.description);
+          lines.push("");
+        }
+        lines.push("**Fields:**");
+        lines.push("");
+        lines.push("| Name | Type | Required |");
+        lines.push("|------|------|----------|");
+        for (const field of model.fields) {
+          const required = field.optional ? "No" : "Yes";
+          lines.push(`| ${field.name} | ${field.type} | ${required} |`);
+        }
+        lines.push("");
+      }
+    }
+    if (schema.components && schema.components.length > 0) {
+      lines.push("## Components");
+      lines.push("");
+      for (const component of schema.components) {
+        lines.push(`### ${component.name}`);
+        lines.push("");
+        lines.push(`**Type:** ${component.type}`);
+        lines.push("");
+        if (component.description) {
+          lines.push(component.description);
+          lines.push("");
+        }
+        if (component.model) {
+          lines.push(`**Model:** ${component.model}`);
+          lines.push("");
+        }
+      }
+    }
+    if (schema.logic && schema.logic.length > 0) {
+      lines.push("## Logic");
+      lines.push("");
+      for (const logic of schema.logic) {
+        lines.push(`### ${logic.id}`);
+        lines.push("");
+        if (logic.description) {
+          lines.push(logic.description);
+          lines.push("");
+        }
+        if (logic.events && logic.events.length > 0) {
+          lines.push("**Events:**");
+          lines.push("");
+          for (const event of logic.events) {
+            lines.push(`- \`${event.tag}\`: ${event.description || ""}`);
+          }
+          lines.push("");
+        }
+        if (logic.facts && logic.facts.length > 0) {
+          lines.push("**Facts:**");
+          lines.push("");
+          for (const fact of logic.facts) {
+            lines.push(`- \`${fact.tag}\`: ${fact.description || ""}`);
+          }
+          lines.push("");
+        }
+        if (logic.rules && logic.rules.length > 0) {
+          lines.push("**Rules:**");
+          lines.push("");
+          for (const rule of logic.rules) {
+            lines.push(`- \`${rule.id}\`: ${rule.description || ""}`);
+          }
+          lines.push("");
+        }
+      }
+    }
+    if (this.config.template?.timestamp) {
+      lines.push("---");
+      lines.push("");
+      lines.push(`*Generated on ${(/* @__PURE__ */ new Date()).toISOString()} by State-Docs*`);
+    }
+    if (this.config.template?.footer) {
+      lines.push("");
+      lines.push(this.config.template.footer);
+    }
+    return {
+      path: `${this.config.target}/README.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate models documentation
+   */
+  generateModelsDoc(schema) {
+    const lines = [
+      "# Models",
+      "",
+      "This document describes all data models defined in the schema.",
+      ""
+    ];
+    if (schema.models) {
+      for (const model of schema.models) {
+        lines.push(`## ${model.name}`);
+        lines.push("");
+        if (model.description) {
+          lines.push(model.description);
+          lines.push("");
+        }
+        lines.push("### Fields");
+        lines.push("");
+        lines.push("| Name | Type | Required | Description |");
+        lines.push("|------|------|----------|-------------|");
+        for (const field of model.fields) {
+          const required = field.optional ? "No" : "Yes";
+          const description = field.description || "-";
+          lines.push(`| ${field.name} | \`${field.type}\` | ${required} | ${description} |`);
+        }
+        lines.push("");
+        if (model.indexes && model.indexes.length > 0) {
+          lines.push("### Indexes");
+          lines.push("");
+          for (const index of model.indexes) {
+            lines.push(`- **${index.name}**: \`${index.fields.join(", ")}\``);
+          }
+          lines.push("");
+        }
+      }
+    }
+    return {
+      path: `${this.config.target}/models.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate components documentation
+   */
+  generateComponentsDoc(schema) {
+    const lines = [
+      "# Components",
+      "",
+      "This document describes all UI components defined in the schema.",
+      ""
+    ];
+    if (schema.components) {
+      for (const component of schema.components) {
+        lines.push(`## ${component.name}`);
+        lines.push("");
+        lines.push(`**Type:** ${component.type}`);
+        lines.push("");
+        if (component.description) {
+          lines.push(component.description);
+          lines.push("");
+        }
+        if (component.model) {
+          lines.push(
+            `**Associated Model:** [${component.model}](./models.md#${component.model.toLowerCase()})`
+          );
+          lines.push("");
+        }
+      }
+    }
+    return {
+      path: `${this.config.target}/components.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate logic documentation
+   */
+  generateLogicDoc(logic) {
+    const lines = [`# ${logic.id}`, ""];
+    if (logic.description) {
+      lines.push(logic.description);
+      lines.push("");
+    }
+    if (logic.events && logic.events.length > 0) {
+      lines.push("## Events");
+      lines.push("");
+      lines.push("| Event | Description | Payload |");
+      lines.push("|-------|-------------|---------|");
+      for (const event of logic.events) {
+        const payload = event.payload ? Object.entries(event.payload).map(([k, v]) => `${k}: ${v}`).join(", ") : "-";
+        lines.push(`| \`${event.tag}\` | ${event.description || "-"} | ${payload} |`);
+      }
+      lines.push("");
+    }
+    if (logic.facts && logic.facts.length > 0) {
+      lines.push("## Facts");
+      lines.push("");
+      lines.push("| Fact | Description | Payload |");
+      lines.push("|------|-------------|---------|");
+      for (const fact of logic.facts) {
+        const payload = fact.payload ? Object.entries(fact.payload).map(([k, v]) => `${k}: ${v}`).join(", ") : "-";
+        lines.push(`| \`${fact.tag}\` | ${fact.description || "-"} | ${payload} |`);
+      }
+      lines.push("");
+    }
+    if (logic.rules && logic.rules.length > 0) {
+      lines.push("## Rules");
+      lines.push("");
+      for (const rule of logic.rules) {
+        lines.push(`### ${rule.id}`);
+        lines.push("");
+        if (rule.description) {
+          lines.push(rule.description);
+          lines.push("");
+        }
+        if (rule.priority !== void 0) {
+          lines.push(`**Priority:** ${rule.priority}`);
+          lines.push("");
+        }
+      }
+    }
+    if (logic.constraints && logic.constraints.length > 0) {
+      lines.push("## Constraints");
+      lines.push("");
+      for (const constraint of logic.constraints) {
+        lines.push(`### ${constraint.id}`);
+        lines.push("");
+        if (constraint.description) {
+          lines.push(constraint.description);
+          lines.push("");
+        }
+        if (constraint.message) {
+          lines.push(`**Error Message:** ${constraint.message}`);
+          lines.push("");
+        }
+      }
+    }
+    return {
+      path: `${this.config.target}/logic/${logic.id}.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate Mermaid diagram for logic
+   */
+  generateLogicDiagram(logic) {
+    const lines = ["stateDiagram-v2"];
+    if (logic.events && logic.facts) {
+      lines.push("    [*] --> Processing");
+      for (const event of logic.events) {
+        lines.push(`    Processing --> ${event.tag.replace(/[^a-zA-Z0-9]/g, "")}: ${event.tag}`);
+      }
+      for (const fact of logic.facts) {
+        lines.push(`    ${fact.tag.replace(/[^a-zA-Z0-9]/g, "")} --> [*]`);
+      }
+    }
+    return {
+      path: `${this.config.target}/logic/${logic.id}.mmd`,
+      content: lines.join("\n"),
+      type: "mermaid"
+    };
+  }
+  /**
+   * Generate rules documentation
+   */
+  generateRulesDoc(rules) {
+    const lines = [
+      "# Rules",
+      "",
+      "This document describes all rules registered in the Praxis engine.",
+      ""
+    ];
+    for (const rule of rules) {
+      lines.push(`## ${rule.id}`);
+      lines.push("");
+      if (rule.description) {
+        lines.push(rule.description);
+        lines.push("");
+      }
+      if (rule.meta?.eventType) {
+        lines.push(`**Triggers on:** \`${rule.meta.eventType}\``);
+        lines.push("");
+      }
+      if (rule.meta?.priority !== void 0) {
+        lines.push(`**Priority:** ${rule.meta.priority}`);
+        lines.push("");
+      }
+    }
+    return {
+      path: `${this.config.target}/rules.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate constraints documentation
+   */
+  generateConstraintsDoc(constraints) {
+    const lines = [
+      "# Constraints",
+      "",
+      "This document describes all constraints (invariants) registered in the Praxis engine.",
+      ""
+    ];
+    for (const constraint of constraints) {
+      lines.push(`## ${constraint.id}`);
+      lines.push("");
+      if (constraint.description) {
+        lines.push(constraint.description);
+        lines.push("");
+      }
+      if (constraint.meta?.errorMessage) {
+        lines.push(`**Error Message:** ${constraint.meta.errorMessage}`);
+        lines.push("");
+      }
+    }
+    return {
+      path: `${this.config.target}/constraints.md`,
+      content: lines.join("\n"),
+      type: "markdown"
+    };
+  }
+  /**
+   * Generate state diagram from registry
+   */
+  generateRegistryDiagram(rules, constraints) {
+    const lines = ["graph TD", "    subgraph Rules"];
+    for (const rule of rules) {
+      const id = rule.id.replace(/[^a-zA-Z0-9]/g, "_");
+      lines.push(`        ${id}["${rule.id}"]`);
+    }
+    lines.push("    end");
+    lines.push("    subgraph Constraints");
+    for (const constraint of constraints) {
+      const id = constraint.id.replace(/[^a-zA-Z0-9]/g, "_");
+      lines.push(`        ${id}["${constraint.id}"]`);
+    }
+    lines.push("    end");
+    return {
+      path: `${this.config.target}/state-diagram.mmd`,
+      content: lines.join("\n"),
+      type: "mermaid"
+    };
+  }
+};
+function createStateDocsGenerator(config) {
+  return new StateDocsGenerator(config);
+}
+function generateDocs(schema, config) {
+  const generator = createStateDocsGenerator(config);
+  return generator.generateFromSchema(schema);
+}
+
+export {
+  StateDocsGenerator,
+  createStateDocsGenerator,
+  generateDocs
+};

package/dist/node/chunk-VOMLVI6V.js

@@ -0,0 +1,197 @@
+// src/core/protocol.ts
+var PRAXIS_PROTOCOL_VERSION = "1.0.0";
+
+// src/core/engine.ts
+function safeClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof globalThis.structuredClone === "function") {
+    try {
+      return globalThis.structuredClone(value);
+    } catch {
+    }
+  }
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  return { ...value };
+}
+var LogicEngine = class {
+  state;
+  registry;
+  constructor(options) {
+    this.registry = options.registry;
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+  /**
+   * Get the current state (immutable copy)
+   */
+  getState() {
+    return {
+      context: safeClone(this.state.context),
+      facts: [...this.state.facts],
+      meta: this.state.meta ? safeClone(this.state.meta) : void 0,
+      protocolVersion: this.state.protocolVersion
+    };
+  }
+  /**
+   * Get the current context
+   */
+  getContext() {
+    return safeClone(this.state.context);
+  }
+  /**
+   * Get current facts
+   */
+  getFacts() {
+    return [...this.state.facts];
+  }
+  /**
+   * Process events through the engine.
+   * Applies all registered rules and checks all registered constraints.
+   *
+   * @param events Events to process
+   * @returns Result with new state and diagnostics
+   */
+  step(events) {
+    const config = {
+      ruleIds: this.registry.getRuleIds(),
+      constraintIds: this.registry.getConstraintIds()
+    };
+    return this.stepWithConfig(events, config);
+  }
+  /**
+   * Process events with specific rule and constraint configuration.
+   *
+   * @param events Events to process
+   * @param config Step configuration
+   * @returns Result with new state and diagnostics
+   */
+  stepWithConfig(events, config) {
+    const diagnostics = [];
+    let newState = { ...this.state };
+    const newFacts = [];
+    for (const ruleId of config.ruleIds) {
+      const rule = this.registry.getRule(ruleId);
+      if (!rule) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Rule "${ruleId}" not found in registry`,
+          data: { ruleId }
+        });
+        continue;
+      }
+      try {
+        const ruleFacts = rule.impl(newState, events);
+        newFacts.push(...ruleFacts);
+      } catch (error) {
+        diagnostics.push({
+          kind: "rule-error",
+          message: `Error executing rule "${ruleId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { ruleId, error }
+        });
+      }
+    }
+    newState = {
+      ...newState,
+      facts: [...newState.facts, ...newFacts]
+    };
+    for (const constraintId of config.constraintIds) {
+      const constraint = this.registry.getConstraint(constraintId);
+      if (!constraint) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Constraint "${constraintId}" not found in registry`,
+          data: { constraintId }
+        });
+        continue;
+      }
+      try {
+        const result = constraint.impl(newState);
+        if (result === false) {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: `Constraint "${constraintId}" violated`,
+            data: { constraintId, description: constraint.description }
+          });
+        } else if (typeof result === "string") {
+          diagnostics.push({
+            kind: "constraint-violation",
+            message: result,
+            data: { constraintId, description: constraint.description }
+          });
+        }
+      } catch (error) {
+        diagnostics.push({
+          kind: "constraint-violation",
+          message: `Error checking constraint "${constraintId}": ${error instanceof Error ? error.message : String(error)}`,
+          data: { constraintId, error }
+        });
+      }
+    }
+    this.state = newState;
+    return {
+      state: newState,
+      diagnostics
+    };
+  }
+  /**
+   * Update the context directly (for exceptional cases).
+   * Generally, context should be updated through rules.
+   *
+   * @param updater Function that produces new context from old context
+   */
+  updateContext(updater) {
+    this.state = {
+      ...this.state,
+      context: updater(this.state.context)
+    };
+  }
+  /**
+   * Add facts directly (for exceptional cases).
+   * Generally, facts should be added through rules.
+   *
+   * @param facts Facts to add
+   */
+  addFacts(facts) {
+    this.state = {
+      ...this.state,
+      facts: [...this.state.facts, ...facts]
+    };
+  }
+  /**
+   * Clear all facts
+   */
+  clearFacts() {
+    this.state = {
+      ...this.state,
+      facts: []
+    };
+  }
+  /**
+   * Reset the engine to initial state
+   */
+  reset(options) {
+    this.state = {
+      context: options.initialContext,
+      facts: options.initialFacts ?? [],
+      meta: options.initialMeta ?? {},
+      protocolVersion: PRAXIS_PROTOCOL_VERSION
+    };
+  }
+};
+function createPraxisEngine(options) {
+  return new LogicEngine(options);
+}
+
+export {
+  PRAXIS_PROTOCOL_VERSION,
+  LogicEngine,
+  createPraxisEngine
+};