flex-md 1.1.0 → 3.0.0

package/dist/ofs/enricher.js

@@ -0,0 +1,77 @@
+/**
+ * Generates Markdown guidance instructions for the LLM based on the OFS and contract level.
+ * Strictly avoids the word "flex-md" and remains "tax-aware" by only including relevant rules.
+ */
+export function buildMarkdownGuidance(spec, strict, opts) {
+    const level = strict.level ?? 0;
+    const fence = opts?.containerFence === "flexmd" ? "```flexmd" : "```markdown";
+    // L0 - Minimal Markdown
+    if (level === 0) {
+        return "Reply in Markdown.";
+    }
+    const lines = [];
+    // L2+ Container Rule
+    if (level >= 2) {
+        lines.push(`Return your entire answer inside a single ${fence} fenced block and nothing else.`);
+        lines.push("");
+        lines.push("Inside the block, include these section headings somewhere (order does not matter):");
+    }
+    else {
+        lines.push("Reply in Markdown.");
+        lines.push("");
+        lines.push("Include these section headings somewhere (order does not matter):");
+    }
+    // Heading List
+    for (const s of spec.sections) {
+        let suffix = "";
+        if (level >= 3) {
+            if (s.kind === "list")
+                suffix = " (list)";
+            else if (s.kind === "ordered_list")
+                suffix = " (ordered list)";
+        }
+        lines.push(`- ${s.name}${suffix}`);
+    }
+    lines.push("");
+    // None Rule
+    const noneRule = opts?.includeNoneRule ?? "auto";
+    const hasRequired = spec.sections.some(s => s.required !== false);
+    const includeNone = noneRule === "always" || (noneRule === "auto" && (hasRequired || level >= 3));
+    if (includeNone) {
+        lines.push(`If a section is empty, write \`None\`.`);
+        lines.push("");
+    }
+    // List Rules
+    const listRule = opts?.includeListRules ?? "auto";
+    const hasListDecls = spec.sections.some(s => s.kind === "list" || s.kind === "ordered_list");
+    const includeList = listRule === "always" || (listRule === "auto" && (hasListDecls || level >= 3));
+    if (includeList) {
+        lines.push("List rules:");
+        lines.push("- Use numbered lists (`1.`, `2.`, …) for ordered lists.");
+        lines.push("- Use `-` bullets for unordered lists.");
+        lines.push("");
+    }
+    // Table Rules
+    const tableRule = opts?.includeTableRules ?? "auto";
+    const hasTableDecls = (spec.tables && spec.tables.length > 0) || spec.sections.some(s => s.kind === "table" || s.kind === "ordered_table");
+    const includeTable = tableRule === "always" || (tableRule === "auto" && (hasTableDecls || level >= 3));
+    if (includeTable) {
+        const hasOrderedTable = spec.tables?.some(t => t.kind === "ordered_table") || spec.sections.some(s => s.kind === "ordered_table");
+        lines.push("Tables:");
+        lines.push("- If you include a table, use a Markdown pipe table.");
+        if (hasOrderedTable || level >= 3) {
+            lines.push("- For ordered tables, add a first column named `#` and number rows 1..N.");
+        }
+        lines.push("");
+    }
+    if (level >= 3) {
+        lines.push("Do not return JSON as the response format.");
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * @deprecated Use buildMarkdownGuidance
+ */
+export function enrichInstructions(spec, strict) {
+    return buildMarkdownGuidance(spec, strict);
+}

package/dist/ofs/extractor.d.ts

@@ -0,0 +1,9 @@
+import type { OutputFormatSpec, ExtractedResult } from "../types.js";
+export interface ExtractOptions {
+    /** Parse lists even for prose sections */
+    parseAllLists?: boolean;
+}
+/**
+ * Extract structured data from Markdown based on an OutputFormatSpec.
+ */
+export declare function extractOutput(md: string, spec: OutputFormatSpec, opts?: ExtractOptions): ExtractedResult;

package/dist/ofs/extractor.js

@@ -0,0 +1,75 @@
+import { buildOutline } from "../outline/builder.js";
+import { parseList } from "../parsers/lists.js";
+import { extractAllTables } from "../parsers/tables.js";
+/**
+ * Extract structured data from Markdown based on an OutputFormatSpec.
+ */
+export function extractOutput(md, spec, opts = {}) {
+    const outline = buildOutline(md);
+    const tables = extractAllTables(md);
+    // Index nodes by normalized title
+    const matches = collectMatches(outline.nodes);
+    const sectionsByName = {};
+    // Extract each section
+    for (const section of spec.sections) {
+        const key = normalizeTitle(section.name);
+        const nodes = matches.get(key) ?? [];
+        if (nodes.length === 0) {
+            // Section not found - could add to a "missing" array if needed
+            continue;
+        }
+        // Choose best node (highest level)
+        const chosen = chooseBestNode(nodes);
+        const body = chosen.content_md.trim();
+        const extracted = {
+            nodeKey: chosen.key,
+            nodeLevel: chosen.level,
+            md: body
+        };
+        // Parse lists if required by section kind or if parseAllLists is enabled
+        if (section.kind === "list" || section.kind === "ordered_list" || opts.parseAllLists) {
+            const list = parseList(body);
+            if (list) {
+                extracted.list = list;
+            }
+        }
+        sectionsByName[section.name] = extracted;
+    }
+    return {
+        outline,
+        sectionsByName,
+        tables
+    };
+}
+/**
+ * Collect all nodes by normalized title.
+ */
+function collectMatches(nodes) {
+    const map = new Map();
+    function visit(node) {
+        const key = normalizeTitle(node.title);
+        const existing = map.get(key) ?? [];
+        existing.push(node);
+        map.set(key, existing);
+        node.children.forEach(visit);
+    }
+    nodes.forEach(visit);
+    return map;
+}
+/**
+ * Choose the best node from multiple matches.
+ * Prefer highest-level heading (smallest level number).
+ */
+function chooseBestNode(nodes) {
+    if (nodes.length === 1)
+        return nodes[0];
+    // Sort by level (ascending) and take first
+    const sorted = [...nodes].sort((a, b) => a.level - b.level);
+    return sorted[0];
+}
+/**
+ * Normalize title for comparison: lowercase, remove trailing punctuation.
+ */
+function normalizeTitle(t) {
+    return t.trim().replace(/[:\-–—]\s*$/, "").trim().toLowerCase();
+}

package/dist/ofs/issues.d.ts

@@ -0,0 +1,14 @@
+import type { IssuesEnvelope, FlexMdResponseMode } from "../types.js";
+/**
+ * Detects if the response is an Issues envelope (Mode B).
+ */
+export declare function detectIssuesEnvelope(md: string): boolean;
+/**
+ * Historical alias for processResponseMarkdown.
+ * @deprecated Use detectIssuesEnvelope
+ */
+export declare function detectResponseMode(md: string): FlexMdResponseMode;
+/**
+ * Parses a Markdown Issues envelope into a structured JSON object.
+ */
+export declare function parseIssuesEnvelope(md: string): IssuesEnvelope | null;

package/dist/ofs/issues.js

@@ -0,0 +1,92 @@
+/**
+ * Detects if the response is an Issues envelope (Mode B).
+ */
+export function detectIssuesEnvelope(md) {
+    const hasStatus = /(^|\n)##\s+Status\s*$/im.test(md);
+    const hasIssuesHeading = /(^|\n)##\s+Issues\s*$/im.test(md);
+    const hasStatusLine = /(^|\n)-\s*status:\s*(error|partial)\s*$/im.test(md);
+    return hasStatus && hasIssuesHeading && hasStatusLine;
+}
+/**
+ * Historical alias for processResponseMarkdown.
+ * @deprecated Use detectIssuesEnvelope
+ */
+export function detectResponseMode(md) {
+    return detectIssuesEnvelope(md) ? "issues" : "answer";
+}
+/**
+ * Parses a Markdown Issues envelope into a structured JSON object.
+ */
+export function parseIssuesEnvelope(md) {
+    if (detectResponseMode(md) !== "issues")
+        return null;
+    const statusBlock = sectionBody(md, "Status");
+    const issuesBlock = sectionBody(md, "Issues");
+    if (!statusBlock || !issuesBlock)
+        return null;
+    const statusKv = parseTopLevelKvBullets(statusBlock);
+    const status = {
+        status: statusKv["status"] ?? "error",
+        code: statusKv["code"] ?? "invalid_format",
+        message: statusKv["message"] ?? "An error occurred."
+    };
+    const missingInputs = parseSimpleList(sectionBody(md, "Missing inputs"));
+    const clarificationsNeeded = parseSimpleList(sectionBody(md, "Clarifications needed"));
+    const issues = parseIssueItems(issuesBlock);
+    return {
+        mode: "issues",
+        status,
+        missingInputs: missingInputs.length ? missingInputs : undefined,
+        clarificationsNeeded: clarificationsNeeded.length ? clarificationsNeeded : undefined,
+        issues
+    };
+}
+function sectionBody(md, heading) {
+    const rx = new RegExp(`(^|\\n)##\\s+${escapeRx(heading)}\\s*\\n([\\s\\S]*?)(\\n##\\s+|$)`, "i");
+    const m = md.match(rx);
+    return m ? (m[2] ?? "").trim() : null;
+}
+function parseTopLevelKvBullets(block) {
+    const out = {};
+    for (const line of block.split("\n")) {
+        const m = line.match(/^\s*-\s*([a-zA-Z0-9_-]+)\s*:\s*(.+?)\s*$/);
+        if (m)
+            out[m[1]] = m[2];
+    }
+    return out;
+}
+function parseSimpleList(block) {
+    if (!block)
+        return [];
+    const items = [];
+    for (const line of block.split("\n")) {
+        const m = line.match(/^\s*-\s+(.+?)\s*$/);
+        if (m)
+            items.push(m[1].trim());
+    }
+    return items;
+}
+function parseIssueItems(block) {
+    const lines = block.split("\n");
+    const items = [];
+    let current = null;
+    for (const line of lines) {
+        const top = line.match(/^\s*-\s*issue:\s*(.+?)\s*$/i);
+        if (top) {
+            if (current)
+                items.push(current);
+            current = { issue: top[1].trim() };
+            continue;
+        }
+        const sub = line.match(/^\s{2,}([a-zA-Z0-9_-]+)\s*:\s*(.+?)\s*$/);
+        if (sub && current) {
+            current[sub[1]] = sub[2].trim();
+        }
+    }
+    if (current)
+        items.push(current);
+    return items;
+}
+function escapeRx(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/ofs/issuesEnvelope.d.ts

@@ -0,0 +1,15 @@
+import { IssuesEnvelope, ValidationResult } from "../types.js";
+export declare function parseIssuesEnvelope(md: string): IssuesEnvelope;
+export declare function buildIssuesEnvelope(args: {
+    validation: ValidationResult;
+    level: 0 | 1 | 2 | 3;
+    expectedSummary: string[];
+    foundSummary: string[];
+    howToFix: string[];
+}): string;
+export declare function buildIssuesEnvelopeAuto(args: {
+    validation: ValidationResult;
+    level: 0 | 1 | 2 | 3;
+    requiredSectionNames?: string[];
+    kindRequirements?: string[];
+}): string;

package/dist/ofs/issuesEnvelope.js

@@ -0,0 +1,71 @@
+import { isIssuesEnvelopeCheck } from "../md/parse.js";
+export function parseIssuesEnvelope(md) {
+    return isIssuesEnvelopeCheck(md);
+}
+export function buildIssuesEnvelope(args) {
+    const issues = args.validation.issues
+        .filter(i => i.severity === "warn" || i.severity === "error")
+        .map(i => `- ${i.message}`);
+    const expected = args.expectedSummary.map(x => `- ${x}`);
+    const found = args.foundSummary.map(x => `- ${x}`);
+    const how = args.howToFix.map(x => `- ${x}`);
+    return [
+        "## Status",
+        "Non-compliant output (cannot be repaired to the required format).",
+        "",
+        "## Issues",
+        issues.length ? issues.join("\n") : "- None",
+        "",
+        "## Expected",
+        expected.length ? expected.join("\n") : "- None",
+        "",
+        "## Found",
+        found.length ? found.join("\n") : "- None",
+        "",
+        "## How to fix",
+        how.length ? how.join("\n") : "- None",
+        "",
+    ].join("\n");
+}
+export function buildIssuesEnvelopeAuto(args) {
+    const v = args.validation;
+    const expected = [];
+    const found = [];
+    const how = [];
+    if (args.level >= 2) {
+        expected.push("One single ```markdown fenced block containing the entire answer (no text outside).");
+    }
+    if (args.level >= 1 && (args.requiredSectionNames?.length ?? 0) > 0) {
+        expected.push(`Section headings present (order does not matter): ${args.requiredSectionNames.join(", ")}`);
+    }
+    if (args.level >= 3 && (args.kindRequirements?.length ?? 0) > 0) {
+        for (const k of args.kindRequirements)
+            expected.push(k);
+    }
+    if (v.stats) {
+        found.push(`Detected sections: ${v.stats.sectionCount}`);
+        if (v.stats.missingRequired.length)
+            found.push(`Missing: ${v.stats.missingRequired.join(", ")}`);
+        if (v.stats.duplicates.length)
+            found.push(`Duplicates: ${v.stats.duplicates.join(", ")}`);
+        found.push(`Fences: ${v.stats.container.fenceCount} (langs: ${v.stats.container.fenceLangs.join(", ") || "none"})`);
+        found.push(`Outside text: ${v.stats.container.hasOutsideText ? "yes" : "no"}`);
+    }
+    if (args.level >= 2)
+        how.push("Return a single ```markdown fenced block and nothing else.");
+    if (args.level >= 1)
+        how.push("Include the required headings and put content under each (order does not matter).");
+    how.push('If a section is empty, write "None".');
+    if (args.level >= 3) {
+        how.push('Use numbered lists ("1.", "2.", …) for ordered lists and "-" bullets for unordered lists.');
+        how.push("Use Markdown pipe tables for table sections; ordered tables include a first column '#'.");
+        how.push("Do not return JSON as the response format.");
+    }
+    return buildIssuesEnvelope({
+        validation: v,
+        level: args.level,
+        expectedSummary: expected,
+        foundSummary: found,
+        howToFix: how,
+    });
+}

package/dist/ofs/parser.d.ts

@@ -0,0 +1,9 @@
+import type { OutputFormatSpec } from "../types.js";
+/**
+ * Parse an Output Format Spec block from Markdown.
+ */
+export interface ParseOfsOptions {
+    headingRegex?: RegExp;
+    allowDelimiterFallbacks?: boolean;
+}
+export declare function parseOutputFormatSpec(md: string, opts?: ParseOfsOptions): OutputFormatSpec | null;

package/dist/ofs/parser.js

@@ -0,0 +1,133 @@
+export function parseOutputFormatSpec(md, opts = {}) {
+    const headingRx = opts.headingRegex ?? /^##\s*Output format\b/i;
+    const lines = md.split("\n");
+    // find OFS start
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (headingRx.test(line)) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    // capture block until next H2 (##) or end
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (/^##\s+/.test(line)) {
+            end = i;
+            break;
+        }
+    }
+    const block = lines.slice(start, end).join("\n");
+    const sections = [];
+    const tables = [];
+    let emptySectionValue;
+    let inTables = false;
+    for (const rawLine of block.split("\n")) {
+        const line = rawLine.trim();
+        if (/^tables\b/i.test(line)) {
+            inTables = true;
+            continue;
+        }
+        if (/^empty sections\b/i.test(line)) {
+            inTables = false;
+            continue;
+        }
+        // Empty section rule
+        const mNone = line.match(/write\s+`([^`]+)`/i);
+        if (/empty/i.test(line) && mNone) {
+            emptySectionValue = mNone[1];
+            continue;
+        }
+        // bullet items
+        const bullet = line.match(/^- (.+)$/);
+        if (!bullet)
+            continue;
+        const item = bullet[1];
+        if (inTables) {
+            const t = parseTableDecl(item);
+            if (t)
+                tables.push(t);
+            continue;
+        }
+        const s = parseSectionDecl(item, !!opts.allowDelimiterFallbacks);
+        if (s)
+            sections.push(s);
+    }
+    if (!sections.length)
+        return null;
+    return {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections,
+        tablesOptional: true,
+        tables,
+        emptySectionValue: emptySectionValue ?? "None"
+    };
+}
+function parseSectionDecl(text, allowFallbacks) {
+    const delims = ["—"];
+    if (allowFallbacks)
+        delims.push(":", "-");
+    let best = null;
+    for (const d of delims) {
+        const idx = text.indexOf(d);
+        if (idx > 0) {
+            best = { name: text.slice(0, idx).trim(), rest: text.slice(idx + 1).trim() };
+            break;
+        }
+    }
+    if (!best)
+        return null;
+    const name = best.name;
+    const rest = best.rest;
+    const kind = normalizeSectionKind(rest);
+    if (!kind)
+        return null;
+    const requiredFlag = parseRequiredOptional(rest);
+    return { name, kind, required: requiredFlag };
+}
+function normalizeSectionKind(rest) {
+    const r = rest.toLowerCase();
+    if (r.includes("ordered") && r.includes("list"))
+        return "ordered_list";
+    if (r.includes("list"))
+        return "list";
+    if (r.includes("prose") || r.includes("text"))
+        return "text";
+    return null;
+}
+function parseTableDecl(item) {
+    const m = item.match(/^\((.+)\)\s*(.*)$/);
+    if (!m)
+        return null;
+    const inside = m[1];
+    const parts = inside.split(/[—–-]/).map(s => s.trim());
+    if (parts.length < 2)
+        return null;
+    const colsPart = parts[0];
+    const kindPart = parts.slice(1).join(" — ").trim().toLowerCase();
+    const columns = colsPart.split(",").map(s => s.trim()).filter(Boolean);
+    const requiredFlag = parseRequiredOptional(item);
+    if (kindPart.includes("ordered table")) {
+        const by = (kindPart.match(/\bby\s+([^,)\s]+)/)?.[1] ?? "").trim();
+        return { columns, kind: "ordered_table", by: by || undefined, required: requiredFlag };
+    }
+    if (kindPart.includes("table")) {
+        return { columns, kind: "table", required: requiredFlag };
+    }
+    return null;
+}
+function parseRequiredOptional(s) {
+    const hasReq = /\(required\)/i.test(s);
+    const hasOpt = /\(optional\)/i.test(s);
+    if (hasReq)
+        return true;
+    if (hasOpt)
+        return false;
+    return undefined;
+}

package/dist/ofs/stringify.d.ts

@@ -0,0 +1,5 @@
+import type { OutputFormatSpec } from "../types.js";
+/**
+ * Convert an OutputFormatSpec to canonical Markdown format.
+ */
+export declare function stringifyOutputFormatSpec(spec: OutputFormatSpec): string;

package/dist/ofs/stringify.js

@@ -0,0 +1,32 @@
+/**
+ * Convert an OutputFormatSpec to canonical Markdown format.
+ */
+export function stringifyOutputFormatSpec(spec) {
+    const lines = [];
+    lines.push(`## Output format (Markdown)`);
+    lines.push(`Include these sections somewhere (order does not matter):`);
+    lines.push("");
+    for (const s of spec.sections) {
+        const k = s.kind === "ordered_list" ? "ordered list" : (s.kind || "text");
+        const required = s.required === true ? " (required)" : (s.required === false ? " (optional)" : "");
+        lines.push(`- ${s.name} — ${k}${required}`);
+    }
+    const tables = spec.tables || [];
+    if (tables.length) {
+        lines.push("");
+        lines.push(`tables:`);
+        for (const t of tables) {
+            const required = t.required === true ? " (required)" : (t.required === false ? " (optional)" : "");
+            if (t.kind === "table") {
+                lines.push(`- (${t.columns.join(", ")} — table)${required}`);
+            }
+            else {
+                lines.push(`- (${t.columns.join(", ")} — ordered table, by ${t.by ?? t.columns[0] ?? ""})${required}`);
+            }
+        }
+    }
+    lines.push("");
+    lines.push(`empty sections:`);
+    lines.push(`- If a section is empty, write \`${spec.emptySectionValue ?? "None"}\`.`);
+    return lines.join("\n") + "\n";
+}

package/dist/ofs/validator.d.ts

@@ -0,0 +1,10 @@
+import type { OutputFormatSpec } from "../types.js";
+export interface OfsValidationResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate Markdown output against an OutputFormatSpec.
+ */
+export declare function validateOutput(md: string, spec: OutputFormatSpec): OfsValidationResult;

package/dist/ofs/validator.js

@@ -0,0 +1,91 @@
+import { buildOutline } from "../outline/builder.js";
+/**
+ * Validate Markdown output against an OutputFormatSpec.
+ */
+export function validateOutput(md, spec) {
+    const outline = buildOutline(md);
+    const errors = [];
+    const warnings = [];
+    // Index nodes by normalized title
+    const matches = collectMatches(outline.nodes);
+    // Validate each required section
+    for (const section of spec.sections) {
+        const key = normalizeTitle(section.name);
+        const nodes = matches.get(key) ?? [];
+        if (nodes.length === 0) {
+            errors.push(`missing_section:${section.name}`);
+            continue;
+        }
+        // Choose best node (highest level, i.e., smallest level number)
+        const chosen = chooseBestNode(nodes);
+        const body = chosen.content_md.trim();
+        // Check for empty sections
+        if (spec.emptySectionValue) {
+            if (body === "" && !normalizeNone(body, spec.emptySectionValue)) {
+                errors.push(`empty_section_without_none:${section.name}`);
+            }
+            // If it's "None", skip further validation
+            if (normalizeNone(body, spec.emptySectionValue)) {
+                continue;
+            }
+        }
+        // Validate section kind
+        if (section.kind === "list") {
+            if (!/^\s*-\s+/m.test(body)) {
+                errors.push(`section_not_bullets:${section.name}`);
+            }
+        }
+        if (section.kind === "ordered_list") {
+            if (!/^\s*\d+\.\s+/m.test(body)) {
+                errors.push(`section_not_numbered:${section.name}`);
+            }
+        }
+    }
+    // Validate tables (if any)
+    // Note: Full table validation would require parsing tables from the markdown
+    // For now, we just check if tables exist when required
+    // This is a simplified version; full implementation would use extractAllTables
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Collect all nodes by normalized title.
+ */
+function collectMatches(nodes) {
+    const map = new Map();
+    function visit(node) {
+        const key = normalizeTitle(node.title);
+        const existing = map.get(key) ?? [];
+        existing.push(node);
+        map.set(key, existing);
+        node.children.forEach(visit);
+    }
+    nodes.forEach(visit);
+    return map;
+}
+/**
+ * Choose the best node from multiple matches.
+ * Prefer highest-level heading (smallest level number).
+ */
+function chooseBestNode(nodes) {
+    if (nodes.length === 1)
+        return nodes[0];
+    // Sort by level (ascending) and take first
+    const sorted = [...nodes].sort((a, b) => a.level - b.level);
+    return sorted[0];
+}
+/**
+ * Normalize title for comparison: lowercase, remove trailing punctuation.
+ */
+function normalizeTitle(t) {
+    return t.trim().replace(/[:\-–—]\s*$/, "").trim().toLowerCase();
+}
+/**
+ * Check if body is the "None" value.
+ */
+function normalizeNone(body, noneValue) {
+    return body.trim().toLowerCase() === noneValue.toLowerCase();
+}

package/dist/outline/builder.d.ts

@@ -0,0 +1,10 @@
+import type { MdOutline } from "../types.js";
+/**
+ * Build a nested outline tree from Markdown headings.
+ * Accepts any heading level (#..######) and builds parent/child relationships.
+ */
+export declare function buildOutline(md: string): MdOutline;
+/**
+ * Convert title to slug: lowercase, replace spaces with _, remove special chars
+ */
+export declare function slugify(t: string): string;