nx-md-parser 1.0.0

package/examples/markdown-example.ts

@@ -0,0 +1,221 @@
+/**
+ * Example Usage: Markdown to JSON Transformer
+ * 
+ * Shows how to parse markdown text and transform it to a desired JSON schema
+ */
+
+import { JSONTransformer, Schema, MarkdownParser } from '../src';
+
+// ============================================================================
+// Example 1: Your Exact Use Case
+// ============================================================================
+
+const markdownInput = `### Short Answer
+The asset is a server named server1 with private IP 192.168.1.1. Next steps include documenting it in the CMDB, identifying its OS/role, and performing baseline security and inventory checks.
+
+### Full Answer
+The input specifies a single asset with the following attributes: assetType = server, assetName = server1, assetIp = 192.168.1.1. The IP address falls within a private RFC1918 range, indicating it is intended for internal network use rather than public exposure. To manage this asset effectively, consider the following actions:
+
+- Inventory and ownership: Add server1 to your configuration management database (CMDB) or asset registry with fields for owner, location (rack or data center, if physical), environment (prod, staging, dev), and asset lifecycle data (purchase date, warranty, maintenance contracts).
+- Determine the server's role and baseline: Clarify the operating system, version, installed applications, and the primary function (e.g., web server, application server, database). Establish a baseline configuration and security policies (patching cadence, anti-malware, configuration hardening).
+- Security and compliance checks: Verify that appropriate access controls exist (least privilege, SSH/RDP hardening, multi-factor authentication where applicable), and ensure network segmentation and firewall rules restrict external access. Plan vulnerability management and regular scans, plus backup and recovery testing.
+- Monitoring and maintenance: Ensure logging, monitoring (performance, security events), and alerting are in place. Confirm backup status and disaster recovery procedures, including recovery objectives and RPO/RTO.
+- Information gaps to fill: Owner contact, exact OS and version, hardware vs. VM status, network topology (subnet, gateway, DNS), exposed services/ports, and current patch level.
+
+If you want, I can draft a concrete onboarding checklist or a template CMDB entry for server1 based on your environment.
+
+### Assumptions
+- The asset is intended to be tracked in an internal asset management system (CMDB/CMR).
+- The IP 192.168.1.1 is an internal address and not publicly routable.
+
+### Unknowns
+- Operating system and version running on server1.
+- Physical vs. virtual server status and its exact location/topology.
+
+### Evidence
+1. Asset details provided: assetType = "server", assetName = "server1", assetIp = "192.168.1.1".
+2. The IP address 192.168.1.1 is within the private address space (RFC1918).`;
+
+// Define the desired JSON schema
+const desiredSchema = Schema.object({
+  shortAnswer: Schema.string(),
+  fullAnswer: Schema.string(),
+  assumptions: Schema.array(Schema.string()),
+  unknowns: Schema.array(Schema.string()),
+  evidence: Schema.array(Schema.string()),
+});
+
+// Transform markdown to JSON
+const transformer = new JSONTransformer(desiredSchema);
+const result = transformer.transformMarkdown(markdownInput);
+
+console.log('='.repeat(70));
+console.log('EXAMPLE 1: Markdown to Structured JSON');
+console.log('='.repeat(70));
+console.log('\nStatus:', result.status);
+console.log('\nResult:');
+console.log(JSON.stringify(result.result, null, 2));
+
+if (result.fixes) {
+  console.log('\nFixes applied:');
+  result.fixes.forEach(fix => console.log(`  - ${fix}`));
+}
+
+// ============================================================================
+// Example 2: Nested Schema with Asset Details
+// ============================================================================
+
+const assetSchema = 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()),
+  }),
+});
+
+const transformer2 = new JSONTransformer(assetSchema);
+const result2 = transformer2.transformMarkdown(markdownInput);
+
+console.log('\n' + '='.repeat(70));
+console.log('EXAMPLE 2: Nested Schema Structure');
+console.log('='.repeat(70));
+console.log('\nStatus:', result2.status);
+console.log('\nResult:');
+console.log(JSON.stringify(result2.result, null, 2));
+
+// ============================================================================
+// Example 3: Simple Markdown Sections
+// ============================================================================
+
+const simpleMarkdown = `### Title
+My Project Documentation
+
+### Description  
+This is a detailed description of the project with multiple lines.
+It includes various features and capabilities.
+
+### Tags
+- TypeScript
+- Node.js
+- Nx
+
+### Status
+Active`;
+
+const simpleSchema = Schema.object({
+  title: Schema.string(),
+  description: Schema.string(),
+  tags: Schema.array(Schema.string()),
+  status: Schema.string(),
+});
+
+const transformer3 = new JSONTransformer(simpleSchema);
+const result3 = transformer3.transformMarkdown(simpleMarkdown);
+
+console.log('\n' + '='.repeat(70));
+console.log('EXAMPLE 3: Simple Markdown Sections');
+console.log('='.repeat(70));
+console.log('\nMarkdown Input:');
+console.log(simpleMarkdown);
+console.log('\nStatus:', result3.status);
+console.log('\nResult:');
+console.log(JSON.stringify(result3.result, null, 2));
+
+// ============================================================================
+// Example 4: Using MarkdownParser Directly
+// ============================================================================
+
+const sections = MarkdownParser.parseSections(markdownInput);
+
+console.log('\n' + '='.repeat(70));
+console.log('EXAMPLE 4: Direct Markdown Parsing');
+console.log('='.repeat(70));
+console.log('\nParsed Sections:');
+sections.forEach((section, i) => {
+  console.log(`\n${i + 1}. ${section.heading} (Level ${section.level})`);
+  console.log(`   Content preview: ${section.content.substring(0, 80)}...`);
+});
+
+const parsed = MarkdownParser.sectionsToObject(sections);
+console.log('\nParsed Object:');
+console.log(JSON.stringify(parsed, null, 2));
+
+// ============================================================================
+// Example 5: Flexible Schema Matching
+// ============================================================================
+
+const flexibleMarkdown = `### Short Ans
+Quick summary here
+
+### Full Ans
+Detailed explanation
+
+### Assumtions
+- First assumption
+- Second assumption`;
+
+const flexibleSchema = Schema.object({
+  shortAnswer: Schema.string(),
+  fullAnswer: Schema.string(),
+  assumptions: Schema.array(Schema.string()),
+});
+
+const transformer5 = new JSONTransformer(flexibleSchema, 0.6); // Lower threshold for more fuzzy matching
+const result5 = transformer5.transformMarkdown(flexibleMarkdown);
+
+console.log('\n' + '='.repeat(70));
+console.log('EXAMPLE 5: Fuzzy Matching (Typos in Markdown)');
+console.log('='.repeat(70));
+console.log('\nMarkdown has typos: "Short Ans", "Full Ans", "Assumtions"');
+console.log('\nStatus:', result5.status);
+console.log('\nResult:');
+console.log(JSON.stringify(result5.result, null, 2));
+if (result5.fixes) {
+  console.log('\nFixes applied:');
+  result5.fixes.forEach(fix => console.log(`  - ${fix}`));
+}
+
+// ============================================================================
+// Quick Usage Guide
+// ============================================================================
+
+console.log('\n' + '='.repeat(70));
+console.log('QUICK USAGE GUIDE');
+console.log('='.repeat(70));
+console.log(`
+import { JSONTransformer, Schema } from './markdown-transformer';
+
+// 1. Define your desired JSON schema
+const schema = Schema.object({
+  title: Schema.string(),
+  items: Schema.array(Schema.string()),
+  metadata: Schema.object({
+    author: Schema.string(),
+    date: Schema.string(),
+  }),
+});
+
+// 2. Create transformer
+const transformer = new JSONTransformer(schema);
+
+// 3. Transform markdown to JSON
+const result = transformer.transformMarkdown(yourMarkdownText);
+
+// 4. Use the result
+console.log(result.status);  // 'validated' | 'fixed' | 'failed'
+console.log(result.result);  // Your JSON object
+console.log(result.fixes);   // Array of fixes applied (if any)
+console.log(result.errors);  // Array of errors (if failed)
+
+// Also works with plain objects:
+const objResult = transformer.transform({ title: "Test" });
+`);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "nx-md-parser",
+  "version": "1.0.0",
+  "description": "Nx Markdown Parser - Transform markdown to JSON with schema validation and auto-fixing",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "example": "ts-node examples/markdown-example.ts",
+    "integration-example": "ts-node examples/integration-example.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "markdown",
+    "json",
+    "transformer",
+    "schema",
+    "validation",
+    "parser"
+  ],
+  "author": "nx-md-parser contributors",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/nx-md-parser"
+  },
+  "homepage": "https://github.com/your-org/nx-md-parser#readme",
+  "bugs": {
+    "url": "https://github.com/your-org/nx-md-parser/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "nx-helpers": "^1.2.7"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  }
+}