flex-md 4.2.8 → 4.4.2

package/README.md

@@ -523,46 +523,37 @@ if (status === 'validated' || status === 'fixed') {
 }
 ```
 
-## Integrated OFS Transformation (The "Best of Both Worlds")
+Flex-MD allows you to use its native **Output Format Spec (OFS)** as the source of truth for **NX-MD-Parser's** structured extraction. 
 
-Flex-MD allows you to use its native **Output Format Spec (OFS)** (the markdown-style description) as the source of truth for **NX-MD-Parser's** structured extraction. This combines the simplicity of describing output with markdown and the power of schema-driven JSON transformation.
+### Modern "Smart" Transformation
 
-### Usage:
-
-```typescript
-import { parseOutputFormatSpec, transformWithOfs } from 'flex-md';
+The `transformWithOfs` function is now smarter. It performs **dual parsing**:
+1. **Automatic Parsing**: Even if you don't have a spec, it extracts all sections and camel-cases keys.
+2. **Contract Enforcement**: If you provide a spec, it uses `nx-md-parser` to validate, type-cast (lists/tables), and repair the output.
 
-// 1. Describe your output naturally
-const spec = parseOutputFormatSpec(`
-## Output format
-- Executive Summary — text (required)
-- Key Findings — ordered list (required)
-- Technical Specs — table (optional)
-  Columns: Component, Version, Notes
-`);
+#### Usage with LLM Outputs:
 
-// 2. Transfrom Markdown output using the spec
-const md = `
-### Summary
-The system is fully operational with 99.9% uptime.
+When working with LLMs, pass the **entire response text** directly. Flex-MD handles internal normalization (like escaped `\n` characters) automatically.
 
-### Findings
-1. Scalability improved by 40%
-2. Memory leak in cache module fixed
-`;
+```typescript
+import { transformWithOfs } from 'flex-md';
 
-const { result, status } = transformWithOfs(md, spec);
+// Pass the RAW content string from your LLM provider
+const { 
+  parsedOutput,   // Always populated (auto-extraction)
+  contractOutput, // Populated if spec was provided
+  contractStatus, // "ok" | "different" | "skipped"
+  status          // "validated" | "fixed" | "failed"
+} = transformWithOfs(llmResponseText, spec);
 
-if (status === 'validated' || status === 'fixed') {
-  console.log(result['Executive Summary']); // "The system is fully operational..."
-  console.log(result['Key Findings']);      // ["Scalability improved...", "Memory leak..."]
-}
+console.log(parsedOutput.shortAnswer);
 ```
 
 ### Why use this?
-1. **Fuzzy Matching**: Even if the LLM slightly changes the heading (e.g., "Summary" instead of "Executive Summary"), the adapter will correctly map it based on the spec.
-2. **Type Enforcement**: Lists and Tables are automatically converted to JSON arrays and objects.
-3. **Single Source of Truth**: Use the same spec to guide the LLM AND parse its response.
+1. **Zero-Config Extraction**: Get structured data without writing a schema first.
+2. **Dual-Safe**: Compare what the LLM *sent* (`parsedOutput`) with what the contract *required* (`contractOutput`).
+3. **Internal Normalization**: Handles messy data (escaped newlines, merged code blocks) so you don't have to.
+4. **Fuzzy Matching**: Even if the LLM slightly changes the heading (e.g., "Summary" vs "Executive Summary"), the contract will correctly map it.
 
 ## Advanced AI Features (via NX-MD-Parser 1.4.0)
 
@@ -622,8 +613,8 @@ const md = `
 Everything looks correctly formatted based on initial evidence.
 `;
 
-const { result } = transformWithOfs(md, recallId);
-console.log(result.Confidence); // 0.95
+const { contractOutput } = transformWithOfs(md, recallId);
+console.log(contractOutput.Confidence); // 0.95
 ```
 
 ### Why use this?

package/dist/md/normalize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Centralized normalization for Markdown input.
+ * Handles common LLM output artifacts like literal \n.
+ */
+export declare function normalizeMarkdownInput(md: string): string;

package/dist/md/normalize.js

@@ -0,0 +1,10 @@
+/**
+ * Centralized normalization for Markdown input.
+ * Handles common LLM output artifacts like literal \n.
+ */
+export function normalizeMarkdownInput(md) {
+    if (!md)
+        return "";
+    // Handle literal \n common in LLM outputs delivered via JSON
+    return md.replace(/\\n/g, "\n");
+}

package/dist/md/parse.js

@@ -1,4 +1,5 @@
-import { MarkdownParser } from "nx-md-parser";
+import { toCamelCase } from "nx-helpers";
+import { normalizeMarkdownInput } from "./normalize.js";
 export function normalizeName(s) {
     return s.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -157,8 +158,33 @@ export function isIssuesEnvelopeCheck(md) {
 }
 export function markdownToJson(md) {
     // Robustly handle both actual newlines and literal \n (common in LLM JSON outputs)
-    const normalizedMd = (md || "").replace(/\\n/g, "\n");
-    // Use the powerful nx-md-parser for robust section detection
-    const sections = MarkdownParser.parseSections(normalizedMd);
-    return MarkdownParser.sectionsToObject(sections);
+    const normalizedMd = normalizeMarkdownInput(md);
+    // Collect all bullet names that look like headers ("- Name")
+    // We look for patterns like "- Name\n" at the start of lines, ensuring it's not a sub-bullet.
+    const bulletNames = [];
+    const bulletLinesRx = /^[-*+]\s+([^—:\n\r]{2,50})$/gm;
+    let m;
+    while ((m = bulletLinesRx.exec(normalizedMd)) !== null) {
+        bulletNames.push(m[1].trim());
+    }
+    // Use Flex-MD's native parser (supports === headings and avoids colon-as-object bug)
+    const sections = parseHeadingsAndSections(normalizedMd, { bulletNames });
+    const result = {};
+    for (const sec of sections) {
+        const key = toCamelCase(sec.heading.name);
+        const body = sec.body.trim();
+        // 1. Try to detect list
+        const bullets = extractBullets(body);
+        if (bullets.length > 0) {
+            result[key] = bullets;
+            continue;
+        }
+        // 2. Try to detect table (basic check)
+        const lines = body.split("\n").map(l => l.trim()).filter(l => l);
+        if (lines.length >= 2 && lines[0].startsWith("|") && /^[|\s-:]+$/.test(lines[1])) {
+            // It looks like a table - we could use nx-md-parser's table logic here safely
+        }
+        result[key] = body;
+    }
+    return result;
 }

package/dist/ofs/adapter.d.ts

@@ -1,10 +1,21 @@
-import { type SchemaType, type TransformResult } from "nx-md-parser";
+import { type SchemaType } from "nx-md-parser";
 import { type OutputFormatSpec } from "../types.js";
+/**
+ * Result of a Flex-MD transformation.
+ */
+export interface FlexTransformResult<T = any> {
+    parsedOutput: Record<string, any>;
+    contractOutput: T | null;
+    contractStatus: "ok" | "different" | "skipped";
+    status: "validated" | "fixed" | "failed";
+    errors: string[];
+}
 /**
  * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
  */
 export declare function ofsToSchema(spec: OutputFormatSpec): SchemaType;
 /**
  * Transforms markdown text using a Flex-MD OutputFormatSpec or a recallId.
+ * If no spec is provided, it attempts to infer it from the markdown (autospecs).
  */
-export declare function transformWithOfs<T = any>(md: string, specOrRecallId: OutputFormatSpec | string): TransformResult<T>;
+export declare function transformWithOfs<T = any>(md: string, specOrRecallId?: OutputFormatSpec | string): FlexTransformResult<T>;

package/dist/ofs/adapter.js

@@ -1,6 +1,9 @@
 import { JSONTransformer, Schema } from "nx-md-parser";
 import { recall } from "./memory.js";
 import { parseHeadingsAndSections, extractBullets, parseMarkdownTable, normalizeName } from "../md/parse.js";
+import { normalizeMarkdownInput } from "../md/normalize.js";
+import { toCamelCase } from "nx-helpers";
+import { markdownToJson as autoMarkdownToJson } from "nx-json-parser";
 /**
  * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
  */
@@ -47,30 +50,46 @@ export function ofsToSchema(spec) {
 }
 /**
  * Transforms markdown text using a Flex-MD OutputFormatSpec or a recallId.
+ * If no spec is provided, it attempts to infer it from the markdown (autospecs).
  */
 export function transformWithOfs(md, specOrRecallId) {
+    // 0. Normalize input (handle literal \n common in LLM outputs)
+    const normalizedMd = normalizeMarkdownInput(md);
+    // 1. Automatic parsing (Dual-Response) using nx-json-parser
+    const parsedOutput = autoMarkdownToJson(normalizedMd);
+    if (!specOrRecallId) {
+        return {
+            parsedOutput,
+            contractOutput: null,
+            contractStatus: "skipped",
+            status: "validated",
+            errors: []
+        };
+    }
     let spec;
     if (typeof specOrRecallId === "string") {
-        spec = recall(specOrRecallId);
-        if (!spec) {
+        const recalled = recall(specOrRecallId);
+        if (!recalled) {
             return {
+                parsedOutput,
+                contractOutput: null,
+                contractStatus: "skipped",
                 status: "failed",
-                result: null,
                 errors: [`Recall ID "${specOrRecallId}" not found in memory.`]
             };
         }
+        spec = recalled;
     }
     else {
         spec = specOrRecallId;
     }
-    // 1. Parse sections using Flex-MD parser
+    // 2. Parse sections using Flex-MD parser for the contract mapping
     const bulletNames = spec.sections.map(s => s.name);
-    const parsedSections = parseHeadingsAndSections(md, { bulletNames });
+    // Note: We use the local headings parser to find the specific sections defined in the spec
+    const parsedSections = parseHeadingsAndSections(normalizedMd, { bulletNames });
     const parsedObj = {};
-    // 2. Map sections to OFS and apply complex parsing (tables/lists)
     for (const sectionSpec of spec.sections) {
         const normName = normalizeName(sectionSpec.name);
-        // Find section with similar name
         const found = parsedSections.find(s => normalizeName(s.heading.name) === normName);
         if (found) {
             let value;
@@ -95,8 +114,21 @@ export function transformWithOfs(md, specOrRecallId) {
             parsedObj[sectionSpec.name] = value;
         }
     }
-    // 3. Transform using nx-md-parser for schema validation and auto-fixing
+    // 3. Transform using nx-md-parser (latest v2.2.0) for schema validation and fixing
     const schema = ofsToSchema(spec);
     const transformer = new JSONTransformer(schema);
-    return transformer.transform(parsedObj);
+    const transformResult = transformer.transform(parsedObj);
+    // 4. Compare parsed results with contract results
+    const autoKeys = Object.keys(parsedOutput).sort();
+    const contractKeys = transformResult.result ? Object.keys(transformResult.result).map(k => toCamelCase(k)).sort() : [];
+    const isSame = autoKeys.length > 0 &&
+        autoKeys.every(k => contractKeys.includes(k)) &&
+        contractKeys.length === autoKeys.length;
+    return {
+        parsedOutput,
+        contractOutput: transformResult.result,
+        contractStatus: isSame ? "ok" : "different",
+        status: transformResult.status,
+        errors: transformResult.errors || []
+    };
 }

package/dist/ofs/infer.d.ts

@@ -0,0 +1,5 @@
+import { OutputFormatSpec } from "../types.js";
+/**
+ * Infers an OutputFormatSpec from a Markdown string.
+ */
+export declare function inferOfsFromMarkdown(md: string): OutputFormatSpec;

package/dist/ofs/infer.js

@@ -0,0 +1,60 @@
+import { parseHeadingsAndSections, extractBullets } from "../md/parse.js";
+/**
+ * Infers an OutputFormatSpec from a Markdown string.
+ */
+export function inferOfsFromMarkdown(md) {
+    // Collect all bullet names that look like headers ("- Name")
+    const lines = md.split("\n");
+    const bulletNames = [];
+    for (const line of lines) {
+        // Match "- Name" or "- Name\n" or "- Name " but NOT "- Name: more text"
+        const m = line.match(/^[-*+]\s+([^—:\n]+)$/);
+        if (m) {
+            bulletNames.push(m[1].trim());
+        }
+    }
+    const sections = parseHeadingsAndSections(md, { bulletNames });
+    const specSections = [];
+    for (const sec of sections) {
+        const name = sec.heading.name;
+        const body = sec.body.trim();
+        // 1. Detect list
+        const bullets = extractBullets(body);
+        if (bullets.length > 0) {
+            specSections.push({
+                name,
+                kind: "list",
+                required: true
+            });
+            continue;
+        }
+        // 2. Detect table (basic check)
+        const lines = body.split("\n").map(l => l.trim()).filter(Boolean);
+        if (lines.length >= 2 && lines[0].startsWith("|") && /^[|\s-:]+$/.test(lines[1])) {
+            // Extract columns
+            const cols = lines[0].split("|").map(c => c.trim()).filter(Boolean);
+            specSections.push({
+                name,
+                kind: "table",
+                columns: cols,
+                required: true
+            });
+            continue;
+        }
+        // Default to text
+        specSections.push({
+            name,
+            kind: "text",
+            required: true
+        });
+    }
+    return {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: specSections,
+        tablesOptional: true,
+        tables: [],
+        emptySectionValue: "None"
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.2.8",
+  "version": "4.4.2",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -16,6 +16,9 @@
     "detection",
     "extraction"
   ],
+  "ts-node": {
+    "esm": true
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -44,12 +47,14 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "tsx": "^4.21.0",
     "typescript": "^5.6.3",
     "vitest": "^4.0.16"
   },
   "dependencies": {
     "nd": "^1.2.0",
     "nx-helpers": "^1.5.0",
-    "nx-md-parser": "^2.0.2"
+    "nx-json-parser": "^1.1.0",
+    "nx-md-parser": "^2.2.0"
   }
 }