nx-md-parser 1.0.0

package/examples/integration-example.ts

@@ -0,0 +1,531 @@
+/**
+ * Real-World Integration Example
+ * 
+ * Shows how to use the markdown transformer in a production NX project
+ * with nx-helpers for advanced merging capabilities
+ */
+
+import {
+  JSONTransformer,
+  Schema,
+  mergeTransformResults,
+  jsonToMarkdown,
+  mergeNoRedundancy,
+  mergeMultiple,
+  mergeWithRoles,
+  toCamelCase,
+  anyToMarkdownString
+} from '../src';
+import { json2mdWithTables } from 'nx-helpers';
+
+// ============================================================================
+// Example 1: Asset Analysis Pipeline
+// ============================================================================
+
+interface AssetAnalysis {
+  asset: {
+    type: string;
+    name: string;
+    ip: string;
+  };
+  analysis: {
+    shortAnswer: string;
+    fullAnswer: string;
+  };
+  metadata: {
+    assumptions: string[];
+    unknowns: string[];
+    evidence: string[];
+  };
+}
+
+const assetAnalysisSchema = Schema.object({
+  asset: Schema.object({
+    type: Schema.string(),
+    name: Schema.string(),
+    ip: Schema.string(),
+  }),
+  analysis: Schema.object({
+    shortAnswer: Schema.string(),
+    fullAnswer: Schema.string(),
+  }),
+  metadata: Schema.object({
+    assumptions: Schema.array(Schema.string()),
+    unknowns: Schema.array(Schema.string()),
+    evidence: Schema.array(Schema.string()),
+  }),
+});
+
+/**
+ * Process multiple markdown analysis documents and merge them
+ */
+export function processMultipleAnalyses(markdownDocs: string[]): AssetAnalysis | null {
+  const transformer = new JSONTransformer(assetAnalysisSchema);
+  const results = markdownDocs.map(md => transformer.transformMarkdown(md));
+
+  // Check for failures
+  const failed = results.filter(r => r.status === 'failed');
+  if (failed.length > 0) {
+    console.error('Some analyses failed:', failed.flatMap(f => f.errors));
+    return null;
+  }
+
+  // Merge all results using nx-helpers
+  // Arrays will be merged as UNION (deduplicated)
+  const merged = mergeMultiple<AssetAnalysis>(
+    ...results.map(r => r.result!)
+  );
+
+  return merged;
+}
+
+// ============================================================================
+// Example 2: Configuration from Markdown
+// ============================================================================
+
+interface ServerConfig {
+  servers: Array<{
+    name: string;
+    ip: string;
+    port: number;
+    enabled: boolean;
+  }>;
+  settings: {
+    timeout: number;
+    retries: number;
+    logLevel: string;
+  };
+}
+
+const configSchema = Schema.object({
+  servers: Schema.array(
+    Schema.object({
+      name: Schema.string(),
+      ip: Schema.string(),
+      port: Schema.number(),
+      enabled: Schema.boolean(),
+    })
+  ),
+  settings: Schema.object({
+    timeout: Schema.number(),
+    retries: Schema.number(),
+    logLevel: Schema.string(),
+  }),
+});
+
+/**
+ * Parse server configuration from markdown and merge with defaults
+ */
+export function loadConfigFromMarkdown(
+  markdownConfig: string,
+  defaultConfig: Partial<ServerConfig>
+): Partial<ServerConfig> {
+  const transformer = new JSONTransformer(configSchema);
+  const result = transformer.transformMarkdown(markdownConfig);
+
+  if (result.status === 'failed') {
+    throw new Error(`Config parsing failed: ${result.errors?.join(', ')}`);
+  }
+
+  // Merge with defaults using nx-helpers
+  // This ensures arrays are deduplicated and objects are deep-merged
+  return mergeNoRedundancy(defaultConfig, result.result!);
+}
+
+// ============================================================================
+// Example 3: Multi-Source Data Aggregation
+// ============================================================================
+
+interface ProjectData {
+  metadata: {
+    name: string;
+    version: string;
+    tags: string[];
+  };
+  requirements: {
+    functional: string[];
+    nonFunctional: string[];
+  };
+  risks: {
+    identified: string[];
+    mitigation: string[];
+  };
+}
+
+/**
+ * Aggregate project data from multiple markdown sources
+ * (e.g., requirements.md, risks.md, metadata.md)
+ */
+export function aggregateProjectData(sources: {
+  requirements?: string;
+  risks?: string;
+  metadata?: string;
+}): ProjectData {
+  const metadataSchema = Schema.object({
+    metadata: Schema.object({
+      name: Schema.string(),
+      version: Schema.string(),
+      tags: Schema.array(Schema.string()),
+    }),
+  });
+
+  const requirementsSchema = Schema.object({
+    requirements: Schema.object({
+      functional: Schema.array(Schema.string()),
+      nonFunctional: Schema.array(Schema.string()),
+    }),
+  });
+
+  const risksSchema = Schema.object({
+    risks: Schema.object({
+      identified: Schema.array(Schema.string()),
+      mitigation: Schema.array(Schema.string()),
+    }),
+  });
+
+  const results: Partial<ProjectData>[] = [];
+
+  if (sources.metadata) {
+    const t = new JSONTransformer(metadataSchema);
+    const result = t.transformMarkdown(sources.metadata);
+    if (result.status !== 'failed') results.push(result.result!);
+  }
+
+  if (sources.requirements) {
+    const t = new JSONTransformer(requirementsSchema);
+    const result = t.transformMarkdown(sources.requirements);
+    if (result.status !== 'failed') results.push(result.result!);
+  }
+
+  if (sources.risks) {
+    const t = new JSONTransformer(risksSchema);
+    const result = t.transformMarkdown(sources.risks);
+    if (result.status !== 'failed') results.push(result.result!);
+  }
+
+  // Merge all using nx-helpers
+  return mergeMultiple<ProjectData>(...results);
+}
+
+// ============================================================================
+// Example 4: Validation Pipeline with Error Handling
+// ============================================================================
+
+interface ValidationResult<T> {
+  success: boolean;
+  data?: T;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Transform markdown with comprehensive validation and error handling
+ */
+export function validateAndTransform<T>(
+  markdown: string,
+  schema: any,
+  options?: {
+    requireValidation?: boolean; // If true, only accept "validated" status
+    logFixes?: boolean;
+  }
+): ValidationResult<T> {
+  const transformer = new JSONTransformer(schema);
+  const result = transformer.transformMarkdown(markdown);
+
+  if (result.status === 'failed') {
+    return {
+      success: false,
+      errors: result.errors || ['Unknown error'],
+      warnings: [],
+    };
+  }
+
+  const warnings: string[] = [];
+
+  if (result.status === 'fixed') {
+    if (options?.requireValidation) {
+      return {
+        success: false,
+        errors: ['Validation required but fixes were applied'],
+        warnings: result.fixes || [],
+      };
+    }
+
+    if (options?.logFixes) {
+      console.log('Applied fixes:', result.fixes);
+    }
+
+    warnings.push(...(result.fixes || []));
+  }
+
+  return {
+    success: true,
+    data: result.result as T,
+    errors: [],
+    warnings,
+  };
+}
+
+// ============================================================================
+// Example 5: Incremental Updates with nx-helpers
+// ============================================================================
+
+/**
+ * Update existing configuration by merging new markdown data
+ * Uses nx-helpers to intelligently merge arrays and nested objects
+ */
+export function incrementalConfigUpdate<T>(
+  currentConfig: T,
+  updateMarkdown: string,
+  schema: any
+): T {
+  const transformer = new JSONTransformer(schema);
+  const result = transformer.transformMarkdown(updateMarkdown);
+
+  if (result.status === 'failed') {
+    console.error('Update failed:', result.errors);
+    return currentConfig; // Return unchanged
+  }
+
+  // Use nx-helpers mergeNoRedundancy for intelligent merging
+  // - Arrays: merged as UNION (deduplicated)
+  // - Objects: deep merged
+  // - Primitives: new value wins
+  return mergeNoRedundancy(currentConfig, result.result!);
+}
+
+// ============================================================================
+// Usage Examples
+// ============================================================================
+
+if (require.main === module) {
+  // Example 1: Multi-source aggregation
+  const projectData = aggregateProjectData({
+    metadata: `### Metadata
+name: My Project
+version: 1.0.0
+
+### Tags
+- typescript
+- nx`,
+    requirements: `### Requirements
+#### Functional
+- User authentication
+- Data export
+
+#### Non Functional
+- Performance: < 100ms response
+- Security: OAuth 2.0`,
+    risks: `### Risks
+#### Identified
+- Database scalability
+- Third-party API dependency
+
+#### Mitigation
+- Implement caching
+- Add fallback mechanisms`,
+  });
+
+  console.log('Aggregated Project Data:');
+  console.log(JSON.stringify(projectData, null, 2));
+
+  // Example 2: Incremental update
+  const currentConfig = {
+    servers: [
+      { name: 'server1', ip: '192.168.1.1', port: 8080, enabled: true },
+    ],
+    settings: {
+      timeout: 30,
+      retries: 3,
+      logLevel: 'info',
+    },
+  };
+
+  const updateMarkdown = `### Servers
+- name: server2
+  ip: 192.168.1.2
+  port: 8081
+  enabled: true
+
+### Settings
+timeout: 60
+logLevel: debug`;
+
+  const updated = incrementalConfigUpdate(currentConfig, updateMarkdown, configSchema);
+  
+  console.log('\nIncremental Update Result:');
+  console.log(JSON.stringify(updated, null, 2));
+  // Arrays are merged (server1 + server2), objects deep-merged (timeout, logLevel updated)
+}
+
+// ============================================================================
+// Example 6: JSON to Markdown Generation & Advanced nx-helpers Features
+// ============================================================================
+
+console.log('\n\n======================================================================');
+console.log('EXAMPLE 6: JSON to Markdown Generation & Advanced nx-helpers Features');
+console.log('======================================================================\n');
+
+// Example data that might come from your markdown transformations
+const projectData = {
+  title: "nx-md-parser",
+  version: "1.0.0",
+  description: "A powerful markdown to JSON transformer",
+  features: [
+    "Schema validation",
+    "Auto-fixing capabilities",
+    "nx-helpers integration"
+  ],
+  metadata: {
+    dependencies: {
+      "nx-helpers": "^1.2.7",
+      typescript: "^5.3.0"
+    }
+  }
+};
+
+// Simpler test data like in nx-helpers README
+const simpleData = {
+  title: "Project Alpha",
+  metadata: { version: 1, tags: ["ai", "nx"] }
+};
+
+// 6A: Convert JSON back to markdown using our utility
+console.log('6A: JSON to Markdown Conversion:');
+console.log('----------------------------------');
+console.log('Complex data:');
+console.log(jsonToMarkdown(projectData));
+console.log('\nSimple data (like nx-helpers example):');
+console.log(jsonToMarkdown(simpleData));
+console.log();
+
+// 6B: Demonstrate toCamelCase utility
+console.log('6B: CamelCase Conversion Examples:');
+console.log('-----------------------------------');
+console.log('toCamelCase("hello world"):', toCamelCase("hello world"));
+console.log('toCamelCase("user-profile-settings"):', toCamelCase("user-profile-settings"));
+console.log('toCamelCase("API_KEY"):', toCamelCase("API_KEY"));
+console.log();
+
+// 6C: Demonstrate mergeWithRoles for structured merging
+console.log('6C: Advanced Merging with Roles:');
+console.log('---------------------------------');
+const roleBasedData = [
+  { role: 'frontend', value: { framework: 'React', language: 'TypeScript' } },
+  { role: 'backend', value: { framework: 'Node.js', database: 'PostgreSQL' } },
+  { role: 'devops', value: { cloud: 'AWS', ci: 'GitHub Actions' } }
+];
+
+const mergedByRole = mergeWithRoles(roleBasedData);
+console.log('Merged by role:', JSON.stringify(mergedByRole, null, 2));
+console.log();
+
+// 6D: Demonstrate anyToMarkdownString with different options
+console.log('6D: Advanced Markdown Generation Options:');
+console.log('------------------------------------------');
+console.log('Default formatting:');
+console.log(anyToMarkdownString(projectData));
+console.log('\nWith custom heading level (starts at h3):');
+console.log(anyToMarkdownString(projectData, { level: 3 }));
+console.log('\nWith JSON fallback fencing:');
+console.log(anyToMarkdownString({ complex: { nested: { data: 'value' } } }, { fenceJsonFallback: true }));
+
+// ============================================================================
+// Example 7: Role-Based Merging with mergeWithRoles
+// ============================================================================
+
+console.log('\n\n======================================================================');
+console.log('EXAMPLE 7: Role-Based Merging with mergeWithRoles');
+console.log('======================================================================\n');
+
+// 7A: mergeWithRoles - merge data with specific roles
+console.log('7A: Role-Based Data Merging:');
+console.log('------------------------------');
+
+const roleBasedItems = [
+  { role: 'user-profile', value: { name: 'Alice Johnson', email: 'alice@example.com' } },
+  { role: 'user-preferences', value: { theme: 'dark', notifications: true } },
+  { role: 'user-permissions', value: { canEdit: true, canDelete: false } },
+  { role: 'account-settings', value: { plan: 'premium', storage: '100GB' } }
+];
+
+const mergedByRoleExample = mergeWithRoles(roleBasedItems);
+console.log('Merged by role:', JSON.stringify(mergedByRoleExample, null, 2));
+console.log();
+
+// 7B: Comparison with regular merging
+console.log('7B: Comparison with Regular Merging:');
+console.log('-------------------------------------');
+
+const regularMerge = mergeMultiple(
+  { name: 'Alice Johnson', email: 'alice@example.com' } as any,
+  { theme: 'dark', notifications: true } as any,
+  { canEdit: true, canDelete: false } as any,
+  { plan: 'premium', storage: '100GB' } as any
+);
+
+console.log('Regular mergeMultiple result:');
+console.log(JSON.stringify(regularMerge, null, 2));
+console.log();
+
+// 7C: Advanced role-based merging with nested data
+console.log('7C: Advanced Role-Based Merging (Nested Data):');
+console.log('------------------------------------------------');
+
+const advancedRoles = [
+  {
+    role: 'frontend-config',
+    value: {
+      framework: 'React',
+      styling: { library: 'styled-components', theme: 'dark' }
+    }
+  },
+  {
+    role: 'backend-config',
+    value: {
+      runtime: 'Node.js',
+      database: { type: 'PostgreSQL', connection: { host: 'localhost' } }
+    }
+  },
+  {
+    role: 'deployment-config',
+    value: {
+      environment: 'production',
+      scaling: { minInstances: 2, maxInstances: 10 }
+    }
+  }
+];
+
+const advancedMerged = mergeWithRoles(advancedRoles);
+console.log('Advanced role-based merge:');
+console.log(JSON.stringify(advancedMerged, null, 2));
+
+// ============================================================================
+// Example 8: Schema Loading from Files (Bonus)
+// ============================================================================
+
+console.log('\n\n======================================================================');
+console.log('EXAMPLE 8: Schema Loading from Files (Bonus)');
+console.log('======================================================================\n');
+
+// Note: This example demonstrates the API but requires a schema.json file
+console.log('8A: Schema Loading API:');
+console.log('------------------------');
+console.log('// Create a schema.json file with your schema definition:');
+console.log(`{
+  "type": "object",
+  "properties": {
+    "title": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "active": { "type": "boolean" }
+  }
+}`);
+
+// Then load it:
+// const transformer = createTransformerFromSchemaFile('./schema.json');
+// const result = transformer.transformMarkdown(markdown);
+
+console.log('\nSchema loading functions available:');
+console.log('- loadSchemaFromFile(filePath)');
+console.log('- createTransformerFromSchemaFile(schemaFilePath)');
+console.log('\nThese functions use nx-helpers loadJson for robust file loading.');