flex-md 4.4.7 → 4.4.9

package/dist/detect/json/detectMarkdown.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Helpers for "framed vs frameless" Markdown handling before Flex-MD.
+ *
+ * Goals:
+ * 1) Detect framed markdown (single fenced block) and extract its inner content.
+ * 2) If NOT markdown-ish, force-wrap into a minimal markdown shape so Flex-MD can still parse.
+ *
+ * Notes:
+ * - This is heuristic by design; tune thresholds as you learn your data.
+ */
+export type MarkdownDetection = {
+    isMarkdownLikely: boolean;
+    isFramed: boolean;
+    frameLanguage?: string | null;
+    reasons: string[];
+    stats: {
+        headings: number;
+        atxHeadings: number;
+        setextHeadings: number;
+        unorderedListLines: number;
+        orderedListLines: number;
+        tableRows: number;
+        codeFences: number;
+        inlineCodeSpans: number;
+        mdLinks: number;
+        emphasisTokens: number;
+    };
+};
+export declare function detectMarkdown(text: unknown): MarkdownDetection;
+/**
+ * If the entire payload is a single fenced block, return its inner content.
+ * Otherwise return the original text.
+ *
+ * - Also handles ```md / ```markdown / ```json etc.
+ */
+export declare function stripSingleFence(input: string): {
+    stripped: string;
+    wasFramed: boolean;
+    language: string | null;
+};
+/**
+ * Force-wrap non-markdown text into a minimal heading-based markdown document.
+ * This helps Flex-MD / nx-md-parser operate even when the model returns plain text.
+ *
+ * Choose a heading that exists in your OFS to maximize alignment.
+ * Default: "Full Answer" (common sink section).
+ */
+export declare function forceWrapAsMarkdown(plainText: string, opts?: {
+    heading?: string;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    preserveLeadingWhitespace?: boolean;
+}): string;
+/**
+ * End-to-end "normalize input for Flex-MD" helper:
+ * - If framed: strip the fence (so Flex-MD sees pure markdown)
+ * - Else: if markdown-likely: keep as-is
+ * - Else: wrap as markdown under a chosen heading
+ */
+export declare function normalizeForFlexMd(input: unknown, opts?: {
+    fallbackHeading?: string;
+    fallbackHeadingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+}): {
+    normalizedText: string;
+    detection: MarkdownDetection;
+    wasStripped: boolean;
+    stripLanguage: string | null;
+    wasWrapped: boolean;
+};
+/**
+ * Example integration with Flex-MD:
+ *
+ * import { parseOutputFormatSpec, transformWithOfs } from 'flex-md';
+ *
+ * const spec = parseOutputFormatSpec(ofsMarkdown);
+ * const prep = normalizeForFlexMd(llmText, { fallbackHeading: "Full Answer" });
+ * const out = transformWithOfs(prep.normalizedText, spec);
+ */

package/dist/detect/json/detectMarkdown.js

@@ -0,0 +1,184 @@
+/**
+ * Helpers for "framed vs frameless" Markdown handling before Flex-MD.
+ *
+ * Goals:
+ * 1) Detect framed markdown (single fenced block) and extract its inner content.
+ * 2) If NOT markdown-ish, force-wrap into a minimal markdown shape so Flex-MD can still parse.
+ *
+ * Notes:
+ * - This is heuristic by design; tune thresholds as you learn your data.
+ */
+const SINGLE_FENCE_BLOCK_RE = /^```([a-zA-Z0-9_-]+)?([^\n]*)\n([\s\S]*?)\n```$/;
+const FENCE_OPEN_RE = /(^|\n)```/g;
+export function detectMarkdown(text) {
+    const reasons = [];
+    const raw = typeof text === "string" ? text : JSON.stringify(text ?? "");
+    const s = raw.replace(/\r\n/g, "\n");
+    const codeFences = [...s.matchAll(FENCE_OPEN_RE)].length;
+    // Framed detection (single fenced block)
+    const m = s.match(SINGLE_FENCE_BLOCK_RE);
+    const isFramed = !!m && codeFences === 2;
+    const frameLanguage = isFramed ? (m?.[1] ?? null) : null;
+    if (isFramed)
+        reasons.push("Single fenced code block detected (framed payload).");
+    else if (codeFences > 1)
+        reasons.push("Multiple fenced code blocks detected.");
+    const lines = s.split("\n");
+    const atxHeadings = lines.filter((l) => /^#{1,6}\s+\S/.test(l.trim())).length;
+    let setextHeadings = 0;
+    for (let i = 0; i < lines.length - 1; i++) {
+        const cur = lines[i].trim();
+        const nxt = lines[i + 1].trim();
+        if (cur.length > 0 && (/^={2,}$/.test(nxt) || /^-{2,}$/.test(nxt)))
+            setextHeadings++;
+    }
+    const headings = atxHeadings + setextHeadings;
+    const unorderedListLines = lines.filter((l) => /^\s*[-*+]\s+\S/.test(l)).length;
+    const orderedListLines = lines.filter((l) => /^\s*\d{1,3}([.)])\s+\S/.test(l)).length;
+    const tableRows = lines.filter((l) => {
+        const t = l.trim();
+        if (!t.startsWith("|") || t.length < 3)
+            return false;
+        const pipeCount = (t.match(/\|/g) ?? []).length;
+        return pipeCount >= 2;
+    }).length;
+    const inlineCodeSpans = (s.match(/`[^`\n]+`/g) ?? []).length;
+    const mdLinks = (s.match(/\[[^\]]+\]\([^)]+\)/g) ?? []).length;
+    const emphasisTokens = (s.match(/\*\*[^*\n]+\*\*/g) ?? []).length +
+        (s.match(/__[^_\n]+__/g) ?? []).length +
+        (s.match(/(^|[^*])\*[^*\n]+\*([^*]|$)/g) ?? []).length +
+        (s.match(/(^|[^_])_[^_\n]+_([^_]|$)/g) ?? []).length;
+    // Heuristic decision rules
+    const hasList = unorderedListLines + orderedListLines >= 2;
+    const hasTable = tableRows >= 2;
+    const hasOtherSignals = inlineCodeSpans + mdLinks + emphasisTokens >= 2;
+    let isMarkdownLikely = false;
+    if (isFramed) {
+        isMarkdownLikely = true;
+    }
+    else if (headings >= 2) {
+        isMarkdownLikely = true;
+        reasons.push(`Detected ${headings} markdown heading(s) (>=2).`);
+    }
+    else if (headings >= 1 && (hasList || hasTable)) {
+        isMarkdownLikely = true;
+        reasons.push(`Detected heading(s) plus ${hasList ? "list" : "table"} structure.`);
+    }
+    else if ((hasList && hasTable) || (hasTable && hasOtherSignals) || (hasList && hasOtherSignals)) {
+        isMarkdownLikely = true;
+        reasons.push("Detected multiple markdown structural signals (lists/tables/links/code/emphasis).");
+    }
+    else {
+        reasons.push("Insufficient markdown structure signals; treating as plain text.");
+    }
+    if (/^\s*#{1,6}\s+\S/.test(lines[0] ?? "")) {
+        reasons.push("Text starts with an ATX heading (#...).");
+        isMarkdownLikely = true;
+    }
+    return {
+        isMarkdownLikely,
+        isFramed,
+        frameLanguage,
+        reasons,
+        stats: {
+            headings,
+            atxHeadings,
+            setextHeadings,
+            unorderedListLines,
+            orderedListLines,
+            tableRows,
+            codeFences,
+            inlineCodeSpans,
+            mdLinks,
+            emphasisTokens,
+        },
+    };
+}
+/**
+ * If the entire payload is a single fenced block, return its inner content.
+ * Otherwise return the original text.
+ *
+ * - Also handles ```md / ```markdown / ```json etc.
+ */
+export function stripSingleFence(input) {
+    const s = input.replace(/\r\n/g, "\n").trim();
+    const fenceCount = [...s.matchAll(FENCE_OPEN_RE)].length;
+    if (fenceCount !== 2) {
+        return { stripped: input, wasFramed: false, language: null };
+    }
+    const m = s.match(SINGLE_FENCE_BLOCK_RE);
+    if (!m)
+        return { stripped: input, wasFramed: false, language: null };
+    const lang = (m[1] ?? null);
+    const inner = (m[3] ?? "").trim();
+    return { stripped: inner, wasFramed: true, language: lang };
+}
+/**
+ * Force-wrap non-markdown text into a minimal heading-based markdown document.
+ * This helps Flex-MD / nx-md-parser operate even when the model returns plain text.
+ *
+ * Choose a heading that exists in your OFS to maximize alignment.
+ * Default: "Full Answer" (common sink section).
+ */
+export function forceWrapAsMarkdown(plainText, opts) {
+    const heading = opts?.heading ?? "Full Answer";
+    const level = opts?.level ?? 3;
+    const hashes = "#".repeat(level);
+    const raw = plainText.replace(/\r\n/g, "\n");
+    const body = opts?.preserveLeadingWhitespace ? raw : raw.trim();
+    // If empty, keep it explicit.
+    const safeBody = body.length ? body : "None";
+    return `${hashes} ${heading}\n${safeBody}\n`;
+}
+/**
+ * End-to-end "normalize input for Flex-MD" helper:
+ * - If framed: strip the fence (so Flex-MD sees pure markdown)
+ * - Else: if markdown-likely: keep as-is
+ * - Else: wrap as markdown under a chosen heading
+ */
+export function normalizeForFlexMd(input, opts) {
+    const raw = typeof input === "string" ? input : JSON.stringify(input ?? "");
+    const detection = detectMarkdown(raw);
+    // 1) Strip if framed
+    const { stripped, wasFramed, language } = stripSingleFence(raw);
+    if (wasFramed) {
+        return {
+            normalizedText: stripped,
+            detection,
+            wasStripped: true,
+            stripLanguage: language,
+            wasWrapped: false,
+        };
+    }
+    // 2) Keep if markdown-likely
+    if (detection.isMarkdownLikely) {
+        return {
+            normalizedText: raw,
+            detection,
+            wasStripped: false,
+            stripLanguage: null,
+            wasWrapped: false,
+        };
+    }
+    // 3) Wrap if not markdown-likely
+    const wrapped = forceWrapAsMarkdown(raw, {
+        heading: opts?.fallbackHeading ?? "Full Answer",
+        level: opts?.fallbackHeadingLevel ?? 3,
+    });
+    return {
+        normalizedText: wrapped,
+        detection,
+        wasStripped: false,
+        stripLanguage: null,
+        wasWrapped: true,
+    };
+}
+/**
+ * Example integration with Flex-MD:
+ *
+ * import { parseOutputFormatSpec, transformWithOfs } from 'flex-md';
+ *
+ * const spec = parseOutputFormatSpec(ofsMarkdown);
+ * const prep = normalizeForFlexMd(llmText, { fallbackHeading: "Full Answer" });
+ * const out = transformWithOfs(prep.normalizedText, spec);
+ */

package/dist/detect/json/index.d.ts

@@ -2,6 +2,7 @@ import { DetectJsonAllResult } from "./types.js";
 export * from "./types.js";
 export { detectJsonIntent } from "./detectIntent.js";
 export { detectJsonContainers, detectJsonPresence } from "./detectPresence.js";
+export * from "./detectMarkdown.js";
 export declare function detectJsonAll(textOrMd: string, opts?: {
     parseJson?: boolean;
 }): DetectJsonAllResult;

package/dist/detect/json/index.js

@@ -3,6 +3,7 @@ import { detectJsonContainers, detectJsonPresence } from "./detectPresence.js";
 export * from "./types.js";
 export { detectJsonIntent } from "./detectIntent.js";
 export { detectJsonContainers, detectJsonPresence } from "./detectPresence.js";
+export * from "./detectMarkdown.js";
 export function detectJsonAll(textOrMd, opts) {
     return {
         intent: detectJsonIntent(textOrMd),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.4.7",
+  "version": "4.4.9",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",