@plures/praxis 1.0.3 → 1.1.0

package/src/integrations/state-docs.ts

@@ -1,21 +1,21 @@
 /**
  * State-Docs Integration
- * 
+ *
  * Integration with plures/state-docs - FSM documentation generator for XState projects.
  * Generates Markdown and Mermaid documentation from Praxis state machines and logic.
- * 
+ *
  * Features:
  * - Auto-generate documentation from Praxis schemas
  * - Markdown output with Mermaid diagrams
  * - State machine visualization
  * - Transition documentation
  * - Integration with Praxis logic engine
- * 
+ *
  * @see https://github.com/plures/state-docs
  */
 
-import type { PraxisSchema, LogicDefinition } from "../core/schema/types.js";
-import type { RuleDescriptor, ConstraintDescriptor, PraxisModule } from "../core/rules.js";
+import type { PraxisSchema, LogicDefinition } from '../core/schema/types.js';
+import type { RuleDescriptor, ConstraintDescriptor, PraxisModule } from '../core/rules.js';
 
 /**
  * State-Docs configuration
@@ -130,7 +130,7 @@ export interface TransitionDoc {
  */
 export class StateDocsGenerator {
   private config: StateDocsConfig;
-  
+
   constructor(config: StateDocsConfig) {
     this.config = {
       target: './docs',
@@ -147,26 +147,26 @@ export class StateDocsGenerator {
       ...config,
     };
   }
-  
+
   /**
    * Generate documentation from a Praxis schema
    */
   generateFromSchema(schema: PraxisSchema): GeneratedDoc[] {
     const docs: GeneratedDoc[] = [];
-    
+
     // Generate main README
     docs.push(this.generateSchemaReadme(schema));
-    
+
     // Generate model documentation
     if (schema.models && schema.models.length > 0) {
       docs.push(this.generateModelsDoc(schema));
     }
-    
+
     // Generate component documentation
     if (schema.components && schema.components.length > 0) {
       docs.push(this.generateComponentsDoc(schema));
     }
-    
+
     // Generate logic documentation with state diagrams
     if (schema.logic && schema.logic.length > 0) {
       for (const logic of schema.logic) {
@@ -174,52 +174,52 @@ export class StateDocsGenerator {
         docs.push(this.generateLogicDiagram(logic));
       }
     }
-    
+
     return docs;
   }
-  
+
   /**
    * Generate documentation from a Praxis registry
    */
   generateFromModule<TContext>(module: PraxisModule<TContext>): GeneratedDoc[] {
     const docs: GeneratedDoc[] = [];
-    
+
     // Get all rules and constraints
     const rules = module.rules;
     const constraints = module.constraints;
-    
+
     // Generate rules documentation
     docs.push(this.generateRulesDoc(rules));
-    
+
     // Generate constraints documentation
     docs.push(this.generateConstraintsDoc(constraints));
-    
+
     // Generate state diagram
     docs.push(this.generateRegistryDiagram(rules, constraints));
-    
+
     return docs;
   }
-  
+
   /**
    * Generate the main schema README
    */
   private generateSchemaReadme(schema: PraxisSchema): GeneratedDoc {
     const lines: string[] = [];
-    
+
     // Header
     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('');
     }
-    
+
     // Table of contents
     if (this.config.template?.toc) {
       lines.push('## Table of Contents');
@@ -236,13 +236,13 @@ export class StateDocsGenerator {
       }
       lines.push('');
     }
-    
+
     // Overview
     lines.push('## Overview');
     lines.push('');
     lines.push(`**Version:** ${schema.version}`);
     lines.push('');
-    
+
     // Summary statistics
     lines.push('### Statistics');
     lines.push('');
@@ -252,7 +252,7 @@ export class StateDocsGenerator {
     lines.push(`| Components | ${schema.components?.length || 0} |`);
     lines.push(`| Logic Modules | ${schema.logic?.length || 0} |`);
     lines.push('');
-    
+
     // Models summary
     if (schema.models && schema.models.length > 0) {
       lines.push('## Models');
@@ -275,7 +275,7 @@ export class StateDocsGenerator {
         lines.push('');
       }
     }
-    
+
     // Components summary
     if (schema.components && schema.components.length > 0) {
       lines.push('## Components');
@@ -295,7 +295,7 @@ export class StateDocsGenerator {
         }
       }
     }
-    
+
     // Logic summary
     if (schema.logic && schema.logic.length > 0) {
       lines.push('## Logic');
@@ -307,7 +307,7 @@ export class StateDocsGenerator {
           lines.push(logic.description);
           lines.push('');
         }
-        
+
         // Events
         if (logic.events && logic.events.length > 0) {
           lines.push('**Events:**');
@@ -317,7 +317,7 @@ export class StateDocsGenerator {
           }
           lines.push('');
         }
-        
+
         // Facts
         if (logic.facts && logic.facts.length > 0) {
           lines.push('**Facts:**');
@@ -327,7 +327,7 @@ export class StateDocsGenerator {
           }
           lines.push('');
         }
-        
+
         // Rules
         if (logic.rules && logic.rules.length > 0) {
           lines.push('**Rules:**');
@@ -339,27 +339,27 @@ export class StateDocsGenerator {
         }
       }
     }
-    
+
     // Timestamp
     if (this.config.template?.timestamp) {
       lines.push('---');
       lines.push('');
       lines.push(`*Generated on ${new Date().toISOString()} by State-Docs*`);
     }
-    
+
     // Footer
     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
    */
@@ -370,30 +370,30 @@ export class StateDocsGenerator {
       '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('');
-        
+
         // Indexes
         if (model.indexes && model.indexes.length > 0) {
           lines.push('### Indexes');
@@ -405,14 +405,14 @@ export class StateDocsGenerator {
         }
       }
     }
-    
+
     return {
       path: `${this.config.target}/models.md`,
       content: lines.join('\n'),
       type: 'markdown',
     };
   }
-  
+
   /**
    * Generate components documentation
    */
@@ -423,156 +423,157 @@ export class StateDocsGenerator {
       '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(
+            `**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
    */
   private generateLogicDoc(logic: LogicDefinition): GeneratedDoc {
-    const lines: string[] = [
-      `# ${logic.id}`,
-      '',
-    ];
-    
+    const lines: string[] = [`# ${logic.id}`, ''];
+
     if (logic.description) {
       lines.push(logic.description);
       lines.push('');
     }
-    
+
     // Events
     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(', ')
+        const payload = event.payload
+          ? Object.entries(event.payload)
+              .map(([k, v]) => `${k}: ${v}`)
+              .join(', ')
           : '-';
         lines.push(`| \`${event.tag}\` | ${event.description || '-'} | ${payload} |`);
       }
       lines.push('');
     }
-    
+
     // Facts
     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(', ')
+        const payload = fact.payload
+          ? Object.entries(fact.payload)
+              .map(([k, v]) => `${k}: ${v}`)
+              .join(', ')
           : '-';
         lines.push(`| \`${fact.tag}\` | ${fact.description || '-'} | ${payload} |`);
       }
       lines.push('');
     }
-    
+
     // Rules
     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 !== undefined) {
           lines.push(`**Priority:** ${rule.priority}`);
           lines.push('');
         }
       }
     }
-    
+
     // Constraints
     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
    */
   private generateLogicDiagram(logic: LogicDefinition): GeneratedDoc {
-    const lines: string[] = [
-      'stateDiagram-v2',
-    ];
-    
+    const lines: string[] = ['stateDiagram-v2'];
+
     // Add events as transitions
     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
    */
@@ -583,67 +584,69 @@ export class StateDocsGenerator {
       '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 !== undefined) {
         lines.push(`**Priority:** ${rule.meta.priority}`);
         lines.push('');
       }
     }
-    
+
     return {
       path: `${this.config.target}/rules.md`,
       content: lines.join('\n'),
       type: 'markdown',
     };
   }
-  
+
   /**
    * Generate constraints documentation
    */
-  private generateConstraintsDoc<TContext>(constraints: ConstraintDescriptor<TContext>[]): GeneratedDoc {
+  private generateConstraintsDoc<TContext>(
+    constraints: ConstraintDescriptor<TContext>[]
+  ): GeneratedDoc {
     const lines: string[] = [
       '# 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
    */
@@ -651,26 +654,23 @@ export class StateDocsGenerator {
     rules: RuleDescriptor<TContext>[],
     constraints: ConstraintDescriptor<TContext>[]
   ): GeneratedDoc {
-    const lines: string[] = [
-      'graph TD',
-      '    subgraph Rules',
-    ];
-    
+    const lines: string[] = ['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'),
@@ -681,16 +681,16 @@ export class StateDocsGenerator {
 
 /**
  * Create a State-Docs generator instance
- * 
+ *
  * @example
  * ```typescript
  * import { createStateDocsGenerator } from '@plures/praxis/integrations/state-docs';
- * 
+ *
  * const generator = createStateDocsGenerator({
  *   projectTitle: 'My Project',
  *   target: './docs/api',
  * });
- * 
+ *
  * const docs = generator.generateFromSchema(mySchema);
  * for (const doc of docs) {
  *   await writeFile(doc.path, doc.content);