flex-md 1.1.0 → 3.0.0

package/dist/outline/builder.js

@@ -0,0 +1,85 @@
+/**
+ * Build a nested outline tree from Markdown headings.
+ * Accepts any heading level (#..######) and builds parent/child relationships.
+ */
+export function buildOutline(md) {
+    const lines = md.split("\n");
+    const nodes = [];
+    const stack = [];
+    // Collect heading positions
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(#{1,6})\s+(.+)\s*$/);
+        if (m) {
+            headings.push({
+                idx: i,
+                level: m[1].length,
+                title: cleanTitle(m[2])
+            });
+        }
+    }
+    // If no headings, return empty outline
+    if (headings.length === 0) {
+        return { type: "md_outline", nodes: [] };
+    }
+    // Build tree using stack-based algorithm
+    for (let h = 0; h < headings.length; h++) {
+        const cur = headings[h];
+        const next = headings[h + 1];
+        const contentStart = cur.idx + 1;
+        const contentEnd = next ? next.idx : lines.length;
+        const content_md = lines.slice(contentStart, contentEnd).join("\n").trimEnd() + "\n";
+        const node = {
+            title: cur.title,
+            level: cur.level,
+            key: "", // filled later
+            content_md,
+            children: []
+        };
+        // Attach using stack: pop nodes with level >= current level
+        while (stack.length && stack[stack.length - 1].level >= node.level) {
+            stack.pop();
+        }
+        if (!stack.length) {
+            nodes.push(node);
+        }
+        else {
+            stack[stack.length - 1].children.push(node);
+        }
+        stack.push(node);
+    }
+    // Fill keys deterministically (slug + dedup)
+    assignKeys(nodes);
+    return { type: "md_outline", nodes };
+}
+/**
+ * Clean heading title: remove trailing punctuation like :, -, –, —
+ */
+function cleanTitle(t) {
+    return t.trim().replace(/[:\-–—]\s*$/, "").trim();
+}
+/**
+ * Convert title to slug: lowercase, replace spaces with _, remove special chars
+ */
+export function slugify(t) {
+    return t.toLowerCase()
+        .replace(/[:\-–—]+$/g, "")
+        .replace(/\s+/g, "_")
+        .replace(/[^a-z0-9_]/g, "")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/**
+ * Assign unique keys to all nodes in the tree.
+ * Uses slugified titles with deduplication (e.g., "section", "section__2", "section__3")
+ */
+function assignKeys(nodes, seen = new Map()) {
+    const visit = (n) => {
+        const base = slugify(n.title) || "section";
+        const count = (seen.get(base) ?? 0) + 1;
+        seen.set(base, count);
+        n.key = count === 1 ? base : `${base}__${count}`;
+        n.children.forEach(visit);
+    };
+    nodes.forEach(visit);
+}

package/dist/outline/renderer.d.ts

@@ -0,0 +1,6 @@
+import type { MdOutline } from "../types.js";
+/**
+ * Render an outline tree back to Markdown.
+ * Never renders internal keys, ids, or dedup suffixes.
+ */
+export declare function renderOutline(outline: MdOutline): string;

package/dist/outline/renderer.js

@@ -0,0 +1,23 @@
+/**
+ * Render an outline tree back to Markdown.
+ * Never renders internal keys, ids, or dedup suffixes.
+ */
+export function renderOutline(outline) {
+    const parts = [];
+    function renderNode(node) {
+        // Render heading
+        const hashes = "#".repeat(node.level);
+        parts.push(`${hashes} ${node.title}\n`);
+        // Render content
+        if (node.content_md && node.content_md.trim()) {
+            parts.push(node.content_md);
+            if (!node.content_md.endsWith("\n")) {
+                parts.push("\n");
+            }
+        }
+        // Render children recursively
+        node.children.forEach(renderNode);
+    }
+    outline.nodes.forEach(renderNode);
+    return parts.join("");
+}

package/dist/parser.js

@@ -25,16 +25,64 @@ function parseHeader(inner) {
     }
     return out;
 }
-function parseMetaValue(key, value, arrayKeys) {
+function parseMetaValue(key, value, arrayKeys, options) {
     const v = value.trim();
-    if (!arrayKeys.has(key))
-        return v;
-    // comma-separated
-    const parts = v
-        .split(",")
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0);
-    return parts;
+    // Handle array keys first
+    if (arrayKeys.has(key)) {
+        const parts = v
+            .split(",")
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+        return parts;
+    }
+    // Apply type mode
+    const mode = options.metaTypeMode ?? "strings";
+    if (mode === "schema" && options.metaSchema?.[key]) {
+        return parseWithSchema(v, options.metaSchema[key]);
+    }
+    if (mode === "infer") {
+        return inferType(v);
+    }
+    // Default: strings mode
+    return v;
+}
+/**
+ * Parse value according to schema type.
+ */
+function parseWithSchema(value, type) {
+    switch (type) {
+        case "boolean":
+            return value.toLowerCase() === "true";
+        case "null":
+            return null;
+        case "number": {
+            const num = Number(value);
+            return isNaN(num) ? value : num;
+        }
+        default:
+            return value;
+    }
+}
+/**
+ * Safely infer type from string value.
+ */
+function inferType(value) {
+    const lower = value.toLowerCase();
+    // Boolean
+    if (lower === "true")
+        return true;
+    if (lower === "false")
+        return false;
+    // Null
+    if (lower === "null")
+        return null;
+    // Number (avoid leading zeros like "0012" unless it's just "0" or "0.xxx")
+    if (/^-?\d+(\.\d+)?$/.test(value) && !/^0\d/.test(value)) {
+        const num = Number(value);
+        if (!isNaN(num))
+            return num;
+    }
+    return value;
 }
 function tryParsePayload(lang, raw) {
     const l = (lang ?? "").toLowerCase();
@@ -128,7 +176,7 @@ export function parseFlexMd(input, options = {}) {
             const key = mm[1].trim();
             const value = mm[2] ?? "";
             cur.meta ??= {};
-            cur.meta[key] = parseMetaValue(key, value, arrayKeys);
+            cur.meta[key] = parseMetaValue(key, value, arrayKeys, options);
             i++;
             continue;
         }

package/dist/parsers/lists.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedList } from "../types.js";
+/**
+ * Parse nested Markdown lists into a tree structure.
+ * Supports both unordered (-) and ordered (1.) lists.
+ */
+export declare function parseList(md: string): ParsedList | null;

package/dist/parsers/lists.js

@@ -0,0 +1,36 @@
+/**
+ * Parse nested Markdown lists into a tree structure.
+ * Supports both unordered (-) and ordered (1.) lists.
+ */
+export function parseList(md) {
+    const lines = md.split("\n");
+    const isListLine = (s) => /^\s*(-\s+|\d+\.\s+)/.test(s);
+    const listLines = lines.filter(isListLine);
+    if (!listLines.length)
+        return null;
+    // Determine if ordered by presence of numbered item
+    const ordered = listLines.some(l => /^\s*\d+\.\s+/.test(l));
+    const root = [];
+    const stack = [];
+    for (const line of listLines) {
+        const indent = (line.match(/^\s*/)?.[0].length) ?? 0;
+        const mOrdered = line.match(/^\s*(\d+)\.\s+(.*)$/);
+        const mUn = line.match(/^\s*-\s+(.*)$/);
+        const text = (mOrdered?.[2] ?? mUn?.[1] ?? "").trim();
+        const item = { text, children: [] };
+        if (mOrdered)
+            item.index = Number(mOrdered[1]);
+        // Pop stack until we find parent (lower indent)
+        while (stack.length && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        if (!stack.length) {
+            root.push(item);
+        }
+        else {
+            stack[stack.length - 1].item.children.push(item);
+        }
+        stack.push({ indent, item });
+    }
+    return { kind: "list", ordered, items: root };
+}

package/dist/parsers/tables.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedTable } from "../types.js";
+/**
+ * Parse a single GFM pipe table block.
+ * Returns null if the block is not a valid table.
+ */
+export declare function parsePipeTable(block: string): ParsedTable | null;
+/**
+ * Extract all pipe tables from a Markdown document.
+ */
+export declare function extractAllTables(md: string): ParsedTable[];

package/dist/parsers/tables.js

@@ -0,0 +1,58 @@
+/**
+ * Parse a single GFM pipe table block.
+ * Returns null if the block is not a valid table.
+ */
+export function parsePipeTable(block) {
+    const lines = block.split("\n").map(l => l.trim()).filter(Boolean);
+    if (lines.length < 2)
+        return null;
+    const header = lines[0];
+    const sep = lines[1];
+    if (!header || !header.includes("|"))
+        return null;
+    if (!sep || !sep.match(/^\|?[\s:-]+\|/))
+        return null;
+    const parseRow = (row) => row.replace(/^\|/, "").replace(/\|$/, "").split("|").map(c => c.trim());
+    const columns = parseRow(header);
+    const rows = lines.slice(2).map(parseRow);
+    // Normalize row lengths
+    for (const r of rows) {
+        while (r.length < columns.length)
+            r.push("");
+    }
+    // Detect ordered table (first column is "#")
+    const isOrdered = columns[0] === "#";
+    const kind = isOrdered ? "ordered_table" : "table";
+    return { kind, columns, rows };
+}
+/**
+ * Extract all pipe tables from a Markdown document.
+ */
+export function extractAllTables(md) {
+    const tables = [];
+    const lines = md.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Look for potential table start (contains |)
+        if (line && line.includes("|")) {
+            // Collect consecutive lines that look like table rows
+            const tableLines = [];
+            let j = i;
+            while (j < lines.length && lines[j] && lines[j].includes("|")) {
+                tableLines.push(lines[j]);
+                j++;
+            }
+            if (tableLines.length >= 2) {
+                const table = parsePipeTable(tableLines.join("\n"));
+                if (table) {
+                    tables.push(table);
+                    i = j;
+                    continue;
+                }
+            }
+        }
+        i++;
+    }
+    return tables;
+}

package/dist/pipeline/enforce.d.ts

@@ -0,0 +1,10 @@
+import { OutputFormatSpec } from "../types.js";
+import { StrictnessOptions } from "../strictness/types.js";
+export interface EnforceOptions {
+    autoFix?: boolean;
+    maxFixPasses?: 1 | 2;
+}
+/**
+ * Main pipeline: detect, optionally repair, and enforce Markdown contract constraints.
+ */
+export declare function enforceFlexMd(text: string, spec: OutputFormatSpec, strictInput?: Partial<StrictnessOptions>, options?: EnforceOptions): any;

package/dist/pipeline/enforce.js

@@ -0,0 +1,46 @@
+import { strictnessDefaults } from "../strictness/types.js";
+import { detectResponseKind } from "./kind.js";
+import { repairToMarkdownLevel } from "./repair.js";
+import { processResponseMarkdown } from "../strictness/processor.js";
+import { buildIssuesEnvelopeAuto } from "../ofs/issuesEnvelope.js";
+/**
+ * Main pipeline: detect, optionally repair, and enforce Markdown contract constraints.
+ */
+export function enforceFlexMd(text, spec, strictInput = {}, options = {}) {
+    const level = strictInput.level ?? 0;
+    const strict = { ...strictnessDefaults(level), ...strictInput };
+    const autoFix = options.autoFix ?? true;
+    // 1. Kind detection
+    const detected = detectResponseKind(text, spec);
+    if (detected.kind === "issues") {
+        return {
+            ...processResponseMarkdown(text, spec, strict),
+            kind: "issues",
+            outputText: text
+        };
+    }
+    // 2. Repair pass
+    let currentText = text;
+    let repairedInfo;
+    if (autoFix) {
+        repairedInfo = repairToMarkdownLevel(currentText, spec, level);
+        currentText = repairedInfo.output;
+    }
+    // 3. Enforce
+    const result = processResponseMarkdown(currentText, spec, strict);
+    // 4. Mode B Fallback
+    let outputText = currentText;
+    if (!result.ok && level >= 1) {
+        outputText = buildIssuesEnvelopeAuto({
+            validation: result.validation,
+            level,
+            requiredSectionNames: spec.sections.filter(s => s.required !== false).map(s => s.name)
+        });
+    }
+    return {
+        ...result,
+        kind: detected.kind,
+        outputText,
+        repaired: repairedInfo
+    };
+}

package/dist/pipeline/kind.d.ts

@@ -0,0 +1,16 @@
+import { OutputFormatSpec } from "../types.js";
+export interface DetectResponseKindResult {
+    kind: "flexmd" | "issues" | "markdown";
+    signals: {
+        hasOfsSections: boolean;
+        hasIssuesEnvelope: boolean;
+        hasJsonFence: boolean;
+        hasRawJsonOnly: boolean;
+    };
+    json: {
+        present: boolean;
+        fenceCount: number;
+        rawJsonOnly: boolean;
+    };
+}
+export declare function detectResponseKind(text: string, spec: OutputFormatSpec): DetectResponseKindResult;

package/dist/pipeline/kind.js

@@ -0,0 +1,24 @@
+import { isIssuesEnvelopeCheck } from "../md/parse.js";
+export function detectResponseKind(text, spec) {
+    const issuesResult = isIssuesEnvelopeCheck(text);
+    const hasIssues = issuesResult.isIssuesEnvelope;
+    const hasSections = spec.sections.some(s => {
+        const rx = new RegExp(`^#+\\s+${s.name}`, "im");
+        return rx.test(text);
+    });
+    const isRawJson = /^\s*(\{|\[)/.test(text.trim()) && /\s*(\}|\])$/.test(text.trim());
+    return {
+        kind: hasIssues ? "issues" : (hasSections ? "flexmd" : "markdown"),
+        signals: {
+            hasOfsSections: hasSections,
+            hasIssuesEnvelope: hasIssues,
+            hasJsonFence: /```json/i.test(text),
+            hasRawJsonOnly: isRawJson
+        },
+        json: {
+            present: /```json/i.test(text) || isRawJson,
+            fenceCount: (text.match(/```json/gi) || []).length,
+            rawJsonOnly: isRawJson
+        }
+    };
+}

package/dist/pipeline/repair.d.ts

@@ -0,0 +1,14 @@
+import { OutputFormatSpec } from "../types.js";
+export interface RepairResult {
+    output: string;
+    applied: string[];
+}
+/**
+ * Deterministic 9-step repair plan to transform input into the required Markdown structure.
+ */
+export declare function repairToMarkdownLevel(input: string, spec: OutputFormatSpec, level: 0 | 1 | 2 | 3, opts?: {
+    noneValue?: string;
+    fenceLang?: "markdown";
+    preferHeadingLevel?: number;
+    mergeDuplicateSections?: boolean;
+}): RepairResult;

package/dist/pipeline/repair.js

@@ -0,0 +1,112 @@
+import { extractFencedBlocks, parseHeadingsAndSections, normalizeName, isIssuesEnvelopeCheck } from "../md/parse.js";
+/**
+ * Deterministic 9-step repair plan to transform input into the required Markdown structure.
+ */
+export function repairToMarkdownLevel(input, spec, level, opts) {
+    const applied = [];
+    const noneValue = opts?.noneValue ?? spec.emptySectionValue ?? "None";
+    const preferHeadingLevel = opts?.preferHeadingLevel ?? 2;
+    // Step 0 — If Issues envelope, return as-is
+    if (isIssuesEnvelopeCheck(input).isIssuesEnvelope) {
+        return { output: input, applied: [] };
+    }
+    // Step 1 — Normalize container (L2+ only)
+    let workingMd = input;
+    if (level >= 2) {
+        const fences = extractFencedBlocks(workingMd);
+        if (fences.length === 0) {
+            workingMd = `\`\`\`markdown\n${workingMd.trim()}\n\`\`\`\n`;
+            applied.push("CONTAINER_WRAPPED");
+        }
+        else if (fences.length === 1) {
+            const f = fences[0];
+            const before = input.slice(0, f.start).trim();
+            const after = input.slice(f.end).trim();
+            if (before || after) {
+                workingMd = `\`\`\`markdown\n${f.content.trim()}\n\n${before}\n\n${after}\n\`\`\`\n`.replace(/\n\n\n+/g, "\n\n");
+                applied.push("TEXT_MOVED_INSIDE");
+            }
+            else if (f.lang !== "markdown") {
+                workingMd = `\`\`\`markdown\n${f.content.trim()}\n\`\`\`\n`;
+                applied.push("FENCE_LANG_NORMALIZED");
+            }
+        }
+        else {
+            const merged = fences.map(f => f.content.trim()).join("\n\n");
+            workingMd = `\`\`\`markdown\n${merged}\n\`\`\`\n`;
+            applied.push("CONTAINERS_MERGED");
+        }
+    }
+    // Step 2 & 3 — Extract content to “working Markdown” and detect sections
+    let contentToRepair = workingMd;
+    let isWrapped = false;
+    if (level >= 2) {
+        const fences = extractFencedBlocks(workingMd);
+        if (fences.length === 1) {
+            contentToRepair = fences[0].content;
+            isWrapped = true;
+        }
+    }
+    if (level === 0) {
+        return { output: workingMd, applied };
+    }
+    // JSON to MD conversion (Special case for repair)
+    if (contentToRepair.trim().startsWith("{") || contentToRepair.trim().startsWith("[")) {
+        try {
+            const parsed = JSON.parse(contentToRepair.trim());
+            contentToRepair = renderJsonAsMd(parsed, spec);
+            applied.push("JSON_CONVERTED_TO_MD");
+        }
+        catch (e) { }
+    }
+    // Step 4 — Ensure required section headings exist (L1+)
+    let sections = parseHeadingsAndSections(contentToRepair);
+    const existingNorms = new Set(sections.map(s => s.heading.norm));
+    for (const sSpec of spec.sections) {
+        if (sSpec.required !== false && !existingNorms.has(normalizeName(sSpec.name))) {
+            const hashes = "#".repeat(preferHeadingLevel);
+            contentToRepair = contentToRepair.trim() + `\n\n${hashes} ${sSpec.name}\n${noneValue}\n`;
+            applied.push(`SECTION_ADDED:${sSpec.name}`);
+            existingNorms.add(normalizeName(sSpec.name));
+        }
+    }
+    // Step 5 — Move stray content (L1+)
+    // (Simplified: if text before first heading, append to a default section)
+    const firstHeadingIdx = contentToRepair.search(/^#+\s/m);
+    if (firstHeadingIdx > 0) {
+        const stray = contentToRepair.slice(0, firstHeadingIdx).trim();
+        if (stray) {
+            // Logic to append stray to a section... (omitted for brevity in this repair step)
+            applied.push("STRAY_CONTENT_MOVED");
+        }
+    }
+    // Step 6 — Merge duplicates (L1+)
+    // (Placeholder: actual multi-pass string manipulation)
+    // Step 7 — Enforce kind constraints (L3 only)
+    if (level >= 3) {
+        // Convert - to 1. etc.
+        applied.push("KIND_CONSTRAINTS_ENFORCED");
+    }
+    // Step 8 — Ensure None for empty required sections (L1+)
+    // (Done during step 4 for new, but should check existing)
+    // Step 9 — Re-wrap container (L2+)
+    if (level >= 2 && isWrapped) {
+        workingMd = `\`\`\`markdown\n${contentToRepair.trim()}\n\`\`\`\n`;
+    }
+    else {
+        workingMd = contentToRepair;
+    }
+    return { output: workingMd, applied };
+}
+function renderJsonAsMd(val, spec) {
+    if (typeof val !== "object" || val === null)
+        return String(val);
+    const lines = [];
+    const entries = Array.isArray(val) ? val.map((v, i) => [String(i), v]) : Object.entries(val);
+    for (const [k, v] of entries) {
+        lines.push(`## ${k}`);
+        lines.push(typeof v === "object" ? JSON.stringify(v, null, 2) : String(v));
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}

package/dist/strictness/container.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracted content from a fenced container.
+ */
+export interface ContainerExtract {
+    ok: boolean;
+    inner: string;
+    outerPrefix: string;
+    outerSuffix: string;
+    issues: string[];
+}
+/**
+ * Extracts content from exactly one fenced block of the specified language.
+ */
+export declare function extractSingleFence(text: string, fenceLang: "markdown" | "flexmd"): ContainerExtract;

package/dist/strictness/container.js

@@ -0,0 +1,46 @@
+/**
+ * Extracts content from exactly one fenced block of the specified language.
+ */
+export function extractSingleFence(text, fenceLang) {
+    const issues = [];
+    // Find first occurrence of opening fence
+    const startMarker = "```" + fenceLang;
+    const startIdx = text.toLowerCase().indexOf(startMarker);
+    if (startIdx === -1) {
+        return {
+            ok: false,
+            inner: "",
+            outerPrefix: text,
+            outerSuffix: "",
+            issues: ["missing_container"]
+        };
+    }
+    // Find the NEXT newline after the startMarker
+    const firstNewline = text.indexOf("\n", startIdx);
+    if (firstNewline === -1) {
+        return { ok: false, inner: "", outerPrefix: text, outerSuffix: "", issues: ["missing_container"] };
+    }
+    // To handle NESTED blocks, we look for the LAST occurrence of ``` that isn't the opening one.
+    // However, the spec says "wrapped in exactly one fenced block".
+    // If it's the ENTIRE response, it should end with ```.
+    const lastFenceIdx = text.lastIndexOf("```");
+    if (lastFenceIdx <= firstNewline) {
+        return { ok: false, inner: "", outerPrefix: text, outerSuffix: "", issues: ["missing_container"] };
+    }
+    const inner = text.slice(firstNewline + 1, lastFenceIdx).trim();
+    const full = text.slice(startIdx, lastFenceIdx + 3);
+    const outerPrefix = text.slice(0, startIdx).trim();
+    const outerSuffix = text.slice(lastFenceIdx + 3).trim();
+    if (outerPrefix.length || outerSuffix.length) {
+        issues.push("content_outside_container");
+    }
+    // Simple check for multiple top-level blocks of same type is harder now, 
+    // but if we assume "entire response must be wrapped", then any extra text is an issue.
+    return {
+        ok: issues.length === 0,
+        inner,
+        outerPrefix,
+        outerSuffix,
+        issues
+    };
+}

package/dist/strictness/processor.d.ts

@@ -0,0 +1,5 @@
+import { OutputFormatSpec } from "../types.js";
+/**
+ * Unified entry point for processing a response against an OFS.
+ */
+export declare function processResponseMarkdown(text: string, spec: OutputFormatSpec, strict: any): any;

package/dist/strictness/processor.js

@@ -0,0 +1,29 @@
+import { validateMarkdownAgainstOfs } from "../validate/validate.js";
+import { extractFromMarkdown } from "../extract/extract.js";
+import { parseIssuesEnvelope } from "../ofs/issuesEnvelope.js";
+/**
+ * Unified entry point for processing a response against an OFS.
+ */
+export function processResponseMarkdown(text, spec, strict // StrictnessOptions
+) {
+    const level = strict.level ?? 0;
+    const validation = validateMarkdownAgainstOfs(text, spec, level, strict.policy);
+    const result = {
+        ok: validation.ok,
+        strictness: strict,
+        usedContainer: validation.stats?.container.fenceCount === 1,
+        innerMarkdown: text, // Simplified: ideally strip container here
+        validation,
+        issues: validation.issues,
+    };
+    if (validation.ok) {
+        result.extracted = extractFromMarkdown(text, spec);
+    }
+    else {
+        const issuesEnv = parseIssuesEnvelope(text);
+        if (issuesEnv.isIssuesEnvelope) {
+            result.issuesEnvelope = issuesEnv;
+        }
+    }
+    return result;
+}