nx-md-parser 1.0.0

package/docs/QUICKSTART.md

@@ -0,0 +1,197 @@
+# Quick Start - Your Exact Use Case
+
+## Installation
+
+```bash
+npm install nx-helpers
+# Copy the markdown-transformer.ts file to your project
+```
+
+## Your Exact Example
+
+Here's how to transform your markdown example to JSON:
+
+### Input Markdown
+
+```markdown
+### 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...
+
+### 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).
+```
+
+### Code
+
+```typescript
+import { JSONTransformer, Schema } from './markdown-transformer';
+
+// Define your 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()),
+});
+
+// Your markdown text
+const markdownText = `...`; // Your markdown from above
+
+// Transform it
+const transformer = new JSONTransformer(desiredSchema);
+const result = transformer.transformMarkdown(markdownText);
+
+// Check the result
+console.log(result.status); // "fixed" or "validated"
+console.log(JSON.stringify(result.result, null, 2));
+```
+
+### Output
+
+```json
+{
+  "status": "fixed",
+  "result": {
+    "shortAnswer": "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.",
+    "fullAnswer": "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...",
+    "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": [
+      "Asset details provided: assetType = \"server\", assetName = \"server1\", assetIp = \"192.168.1.1\".",
+      "The IP address 192.168.1.1 is within the private address space (RFC1918)."
+    ]
+  }
+}
+```
+
+## Alternative: Nested Structure
+
+If you prefer a more structured output:
+
+```typescript
+const nestedSchema = 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()),
+  }),
+});
+```
+
+## Using with nx-helpers
+
+Merge multiple transformation results:
+
+```typescript
+import { mergeNoRedundancy } from 'nx-helpers';
+
+const base = transformer1.transform(markdown1).result;
+const override = transformer2.transform(markdown2).result;
+
+const merged = mergeNoRedundancy(base, override);
+// Arrays are merged as UNION (deduplicated)
+// Objects are deep-merged
+// Primitives: override wins
+```
+
+## Key Features You'll Love
+
+✅ **Automatic List Detection**: Bullet points and numbered lists → arrays  
+✅ **Typo Correction**: "Assumtions" → "assumptions"  
+✅ **Case Handling**: "Short Answer" → "shortAnswer"  
+✅ **Type Conversion**: String numbers → actual numbers  
+✅ **Smart Defaults**: Missing fields get sensible defaults  
+✅ **Detailed Fixes**: See exactly what was changed  
+
+## Schema Types Reference
+
+```typescript
+// Primitives
+Schema.string()
+Schema.number()
+Schema.boolean()
+
+// Arrays
+Schema.array(Schema.string())
+Schema.array(Schema.number())
+Schema.array(Schema.object({ ... }))
+
+// Objects (can be nested infinitely)
+Schema.object({
+  name: Schema.string(),
+  nested: Schema.object({
+    deeplyNested: Schema.object({
+      value: Schema.number()
+    })
+  })
+})
+```
+
+## Integration Example
+
+```typescript
+// In your NX project
+import { JSONTransformer, Schema } from './utils/markdown-transformer';
+import { mergeNoRedundancy } from 'nx-helpers';
+
+export function processMarkdownAnalysis(markdown: string) {
+  const schema = Schema.object({
+    shortAnswer: Schema.string(),
+    fullAnswer: Schema.string(),
+    assumptions: Schema.array(Schema.string()),
+    unknowns: Schema.array(Schema.string()),
+    evidence: Schema.array(Schema.string()),
+  });
+
+  const transformer = new JSONTransformer(schema);
+  const result = transformer.transformMarkdown(markdown);
+
+  if (result.status === 'failed') {
+    console.error('Transformation failed:', result.errors);
+    return null;
+  }
+
+  if (result.status === 'fixed') {
+    console.log('Applied fixes:', result.fixes);
+  }
+
+  return result.result;
+}
+```
+
+## Run the Example
+
+```bash
+npm install
+npm run example
+```
+
+This will run all the examples from `markdown-example.ts` including your exact use case.

package/docs/README.md

@@ -0,0 +1,366 @@
+# Markdown to JSON Transformer
+
+A powerful TypeScript library that parses markdown text and transforms it into JSON objects matching a desired schema. Features intelligent auto-fixing for typos, case mismatches, type conversions, and structural reorganization.
+
+## Features
+
+✨ **Markdown Parsing**
+- Automatically parse markdown sections based on headings
+- Extract lists, key-value pairs, and text content
+- Handle nested structures
+
+🔧 **Smart Auto-Fixing**
+- Fix typos in property names using fuzzy matching
+- Handle case mismatches (camelCase, snake_case, Title Case)
+- Convert types automatically (string → number, string → boolean, etc.)
+- Restructure flat objects into nested schemas
+- Add missing properties with sensible defaults
+
+🎯 **Schema Validation**
+- Define schemas using a clean, intuitive syntax
+- Support for string, number, boolean, array, and object types
+- Nested object support with unlimited depth
+- Returns validation status: `validated`, `fixed`, or `failed`
+
+🔄 **nx-helpers Integration**
+- Uses `mergeNoRedundancy` for intelligent object merging
+- Maintains deep equality and deduplication for arrays
+
+## Installation
+
+```bash
+npm install markdown-json-transformer nx-helpers
+```
+
+## Quick Start
+
+```typescript
+import { JSONTransformer, Schema } from 'markdown-json-transformer';
+
+// 1. Define your desired JSON schema
+const schema = Schema.object({
+  title: Schema.string(),
+  tags: 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 markdown = `
+### Title
+My Project
+
+### Tags
+- TypeScript
+- Markdown
+
+### Metadata
+author: John Doe
+date: 2024-01-01
+`;
+
+const result = transformer.transformMarkdown(markdown);
+
+console.log(result.status);  // "validated" or "fixed"
+console.log(result.result);  // Your JSON object
+```
+
+## Your Example Use Case
+
+Transform complex markdown with sections into structured JSON:
+
+```typescript
+const markdownInput = `### Short Answer
+The asset is a server named server1 with private IP 192.168.1.1.
+
+### Full Answer
+The input specifies a single asset with the following attributes...
+
+### Assumptions
+- The asset is intended to be tracked in an internal asset management system.
+- The IP 192.168.1.1 is an internal address.
+
+### Evidence
+1. Asset details provided: assetType = "server"
+2. The IP address is within private address space.
+`;
+
+const schema = Schema.object({
+  shortAnswer: Schema.string(),
+  fullAnswer: Schema.string(),
+  assumptions: Schema.array(Schema.string()),
+  evidence: Schema.array(Schema.string()),
+});
+
+const transformer = new JSONTransformer(schema);
+const result = transformer.transformMarkdown(markdownInput);
+
+// Output:
+{
+  "status": "fixed",
+  "result": {
+    "shortAnswer": "The asset is a server named server1...",
+    "fullAnswer": "The input specifies a single asset...",
+    "assumptions": [
+      "The asset is intended to be tracked...",
+      "The IP 192.168.1.1 is an internal address."
+    ],
+    "evidence": [
+      "Asset details provided: assetType = \"server\"",
+      "The IP address is within private address space."
+    ]
+  }
+}
+```
+
+## Schema Definition API
+
+### Basic Types
+
+```typescript
+Schema.string()   // String type
+Schema.number()   // Number type
+Schema.boolean()  // Boolean type
+```
+
+### Complex Types
+
+```typescript
+// Array of strings
+Schema.array(Schema.string())
+
+// Array of objects
+Schema.array(
+  Schema.object({
+    name: Schema.string(),
+    value: Schema.number(),
+  })
+)
+
+// Nested objects
+Schema.object({
+  user: Schema.object({
+    profile: Schema.object({
+      name: Schema.string(),
+      age: Schema.number(),
+    }),
+  }),
+})
+```
+
+## Transform Results
+
+Every transformation returns a `TransformResult`:
+
+```typescript
+interface TransformResult<T = any> {
+  status: 'validated' | 'fixed' | 'failed';
+  result: T | null;
+  errors?: string[];   // Only present if failed
+  fixes?: string[];    // Only present if fixed
+}
+```
+
+### Status Values
+
+- **`validated`**: Input perfectly matched the schema (no changes needed)
+- **`fixed`**: Input was transformed to match the schema (see `fixes` for details)
+- **`failed`**: Could not transform input to match schema (see `errors`)
+
+## Advanced Features
+
+### Fuzzy Matching Threshold
+
+Control how aggressively the transformer matches property names:
+
+```typescript
+// More permissive matching (default: 0.7)
+const transformer = new JSONTransformer(schema, 0.6);
+
+// Will match:
+// "assumtions" → "assumptions" ✓
+// "usr" → "user" ✓
+// "meta" → "metadata" ✓
+```
+
+### Direct Object Transformation
+
+Transform plain objects (not just markdown):
+
+```typescript
+const input = {
+  "cats": "some text",
+  "color": "white"
+};
+
+const schema = Schema.object({
+  cat: Schema.string(),
+  data: Schema.object({
+    color: Schema.string(),
+  }),
+});
+
+const result = transformer.transform(input);
+
+// Result:
+{
+  "cat": "some text",
+  "data": {
+    "color": "white"
+  }
+}
+```
+
+### Merging Multiple Results
+
+### Merging Multiple Results (Optional)
+
+For advanced use cases where you need to merge results from multiple transformations:
+
+**Option 1: Use the built-in helper (recommended)**
+```typescript
+import { mergeTransformResults } from 'markdown-json-transformer';
+
+const result1 = transformer1.transform(input1);
+const result2 = transformer2.transform(input2);
+
+const merged = mergeTransformResults(result1, result2);
+```
+
+**Option 2: Use nx-helpers directly**
+```typescript
+import { mergeNoRedundancy } from 'nx-helpers';
+
+const result1 = transformer1.transform(input1);
+const result2 = transformer2.transform(input2);
+
+const merged = mergeNoRedundancy(result1.result, result2.result);
+```
+
+## Markdown Parsing Details
+
+### Section Detection
+
+The parser recognizes markdown headings (H1-H6):
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+```
+
+Each heading becomes a property in the resulting JSON object (converted to camelCase).
+
+### Content Types
+
+**Lists** → Arrays:
+```markdown
+### Tags
+- TypeScript
+- Node.js
+```
+→ `{ tags: ["TypeScript", "Node.js"] }`
+
+**Key-Value Pairs** → Objects:
+```markdown
+### Metadata
+author: John Doe
+date: 2024-01-01
+```
+→ `{ metadata: { author: "John Doe", date: "2024-01-01" } }`
+
+**Plain Text** → Strings:
+```markdown
+### Description
+This is a description.
+```
+→ `{ description: "This is a description." }`
+
+## Type Conversions
+
+The transformer handles intelligent type conversions:
+
+```typescript
+// String to Number
+"42" → 42
+"3.14" → 3.14
+"1,234" → 1234
+
+// String to Boolean  
+"true" → true
+"yes" → true
+"1" → true
+"false" → false
+
+// Boolean to Number
+true → 1
+false → 0
+
+// Any to String
+42 → "42"
+{a: 1} → '{"a":1}'
+```
+
+## Examples
+
+See `markdown-example.ts` for comprehensive examples including:
+
+1. Your exact use case (markdown sections to JSON)
+2. Nested schema structures
+3. Simple markdown parsing
+4. Direct markdown section parsing
+5. Fuzzy matching with typos
+
+Run examples:
+
+```bash
+npm run example
+```
+
+## API Reference
+
+### `JSONTransformer`
+
+```typescript
+class JSONTransformer {
+  constructor(schema: SchemaType, fuzzyMatchThreshold?: number);
+  
+  transformMarkdown(markdown: string): TransformResult;
+  transform(input: any): TransformResult;
+}
+```
+
+### `MarkdownParser`
+
+```typescript
+class MarkdownParser {
+  static parseSections(markdown: string): MarkdownSection[];
+  static sectionsToObject(sections: MarkdownSection[]): Record<string, any>;
+  static parseContent(content: string): any;
+}
+```
+
+### `Schema`
+
+```typescript
+const Schema = {
+  string(): SchemaType;
+  number(): SchemaType;
+  boolean(): SchemaType;
+  array(items: SchemaType): SchemaType;
+  object(properties: Record<string, SchemaType>): SchemaType;
+};
+```
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.