flex-md 2.0.0 → 3.0.0

package/dist/md/outline.js

@@ -0,0 +1,67 @@
+/**
+ * Builds a nested outline tree from Markdown headings.
+ * Supports any heading level and captures content between headings.
+ */
+export function buildOutline(md) {
+    const lines = md.split("\n");
+    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 (!headings.length) {
+        return { type: "md_outline", nodes: [] };
+    }
+    const nodes = [];
+    const stack = [];
+    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: "",
+            content_md,
+            children: []
+        };
+        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);
+    }
+    assignKeys(nodes);
+    return { type: "md_outline", nodes };
+}
+function cleanTitle(t) {
+    return t.trim().replace(/[:\-–—]\s*$/, "").trim();
+}
+function slugify(t) {
+    return t.toLowerCase()
+        .replace(/[:\-–—]+$/g, "")
+        .replace(/\s+/g, "_")
+        .replace(/[^a-z0-9_]/g, "")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function assignKeys(nodes) {
+    const 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/md/parse.d.ts

@@ -0,0 +1,29 @@
+import { IssuesEnvelope } from "../types.js";
+export interface FenceBlock {
+    lang: string;
+    start: number;
+    end: number;
+    contentStart: number;
+    contentEnd: number;
+    content: string;
+    full: string;
+}
+export declare function normalizeName(s: string): string;
+export declare function extractFencedBlocks(text: string): FenceBlock[];
+export interface ParsedHeading {
+    level: number;
+    raw: string;
+    name: string;
+    norm: string;
+    start: number;
+    end: number;
+}
+export interface ParsedSection {
+    heading: ParsedHeading;
+    bodyStart: number;
+    bodyEnd: number;
+    body: string;
+}
+export declare function parseHeadingsAndSections(md: string): ParsedSection[];
+export declare function extractBullets(body: string): string[];
+export declare function isIssuesEnvelopeCheck(md: string): IssuesEnvelope;

package/dist/md/parse.js

@@ -0,0 +1,105 @@
+export function normalizeName(s) {
+    return s.trim().replace(/\s+/g, " ").toLowerCase();
+}
+export function extractFencedBlocks(text) {
+    const rx = /```(\w+)?\s*\n([\s\S]*?)\n```/g;
+    const blocks = [];
+    let m;
+    while ((m = rx.exec(text)) !== null) {
+        const full = m[0];
+        const lang = String(m[1] ?? "").trim().toLowerCase();
+        const content = m[2] ?? "";
+        const start = m.index;
+        const end = start + full.length;
+        // compute content start/end (best-effort)
+        const headerLen = full.indexOf("\n") + 1; // after first newline
+        const contentEnd = end - 3; // "```" at end
+        const contentStart = start + headerLen;
+        blocks.push({
+            lang,
+            start,
+            end,
+            contentStart,
+            contentEnd,
+            content,
+            full,
+        });
+    }
+    return blocks;
+}
+export function parseHeadingsAndSections(md) {
+    const rx = /^(#{1,6})\s+(.+?)\s*$/gm;
+    const headings = [];
+    let m;
+    while ((m = rx.exec(md)) !== null) {
+        const hashes = m[1] ?? "";
+        const name = (m[2] ?? "").trim();
+        const raw = m[0] ?? "";
+        const start = m.index;
+        const end = start + raw.length;
+        headings.push({
+            level: hashes.length,
+            raw,
+            name,
+            norm: normalizeName(name),
+            start,
+            end,
+        });
+    }
+    // compute section bodies
+    const sections = [];
+    for (let i = 0; i < headings.length; i++) {
+        const h = headings[i];
+        const bodyStart = nextLineIndex(md, h.end);
+        let bodyEnd = md.length;
+        for (let j = i + 1; j < headings.length; j++) {
+            const nxt = headings[j];
+            bodyEnd = nxt.start;
+            break;
+        }
+        sections.push({
+            heading: h,
+            bodyStart,
+            bodyEnd,
+            body: md.slice(bodyStart, bodyEnd).trimEnd(),
+        });
+    }
+    return sections;
+}
+function nextLineIndex(text, idx) {
+    if (idx >= text.length)
+        return text.length;
+    if (text[idx] === "\n")
+        return idx + 1;
+    const n = text.indexOf("\n", idx);
+    return n === -1 ? text.length : n + 1;
+}
+export function extractBullets(body) {
+    const lines = body.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const m = line.match(/^\s*[-*]\s+(.*)\s*$/);
+        if (m)
+            out.push(m[1] ?? "");
+    }
+    return out;
+}
+export function isIssuesEnvelopeCheck(md) {
+    const parsed = parseHeadingsAndSections(md);
+    const want = ["status", "issues", "expected", "found", "how to fix"].map(normalizeName);
+    const got = new Set(parsed.map(s => s.heading.norm));
+    const ok = want.every(w => got.has(w));
+    const sections = {};
+    if (ok) {
+        for (const sec of parsed) {
+            if (want.includes(sec.heading.norm)) {
+                sections[sec.heading.norm] = {
+                    heading: sec.heading.name,
+                    body: sec.body.trim(),
+                    bullets: extractBullets(sec.body),
+                };
+            }
+        }
+    }
+    return { isIssuesEnvelope: ok, sections };
+}

package/dist/md/tables.d.ts

@@ -0,0 +1,25 @@
+export interface ParsedTable {
+    kind: "table" | "ordered_table";
+    by?: string;
+    columns: string[];
+    rows: string[][];
+}
+/**
+ * Extracts all pipe table blocks from a markdown string.
+ */
+export declare function extractPipeTables(md: string): string[];
+/**
+ * Parses a single pipe table block into columns and rows.
+ */
+export declare function parsePipeTable(block: string): {
+    columns: string[];
+    rows: string[][];
+} | null;
+export declare function normalizeHeader(s: string): string;
+/**
+ * Enforces ordered table constraints (must have '#' column numbered 1..N).
+ */
+export declare function enforceOrderedTable(table: {
+    columns: string[];
+    rows: string[][];
+}): string[];

package/dist/md/tables.js

@@ -0,0 +1,72 @@
+/**
+ * Extracts all pipe table blocks from a markdown string.
+ */
+export function extractPipeTables(md) {
+    const lines = md.split("\n");
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        const h = lines[i] ?? "";
+        const s = lines[i + 1] ?? "";
+        const looksHeader = h.includes("|");
+        const looksSep = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/.test(s);
+        if (looksHeader && looksSep) {
+            const start = i;
+            i += 2;
+            while (i < lines.length && (lines[i] ?? "").includes("|") && (lines[i] ?? "").trim() !== "") {
+                i++;
+            }
+            const block = lines.slice(start, i).join("\n");
+            blocks.push(block);
+            continue;
+        }
+        i++;
+    }
+    return blocks;
+}
+/**
+ * Parses a single pipe table block into columns and rows.
+ */
+export function parsePipeTable(block) {
+    const lines = block.split("\n").map(l => l.trim()).filter(Boolean);
+    if (lines.length < 2)
+        return null;
+    const parseRow = (row) => {
+        let content = row;
+        if (content.startsWith("|"))
+            content = content.slice(1);
+        if (content.endsWith("|"))
+            content = content.slice(0, -1);
+        return content.split("|").map(c => c.trim());
+    };
+    const columns = parseRow(lines[0]);
+    const rows = lines.slice(2).map(parseRow);
+    for (const r of rows) {
+        while (r.length < columns.length)
+            r.push("");
+    }
+    return { columns, rows };
+}
+export function normalizeHeader(s) {
+    return s.trim().toLowerCase();
+}
+/**
+ * Enforces ordered table constraints (must have '#' column numbered 1..N).
+ */
+export function enforceOrderedTable(table) {
+    const issues = [];
+    if (!table.columns.length || normalizeHeader(table.columns[0]) !== "#") {
+        issues.push("ordered_table_missing_hash_column");
+        return issues;
+    }
+    // enforce 1..N
+    for (let i = 0; i < table.rows.length; i++) {
+        const cell = (table.rows[i]?.[0] ?? "").trim();
+        const n = Number(cell);
+        if (!Number.isInteger(n) || n !== i + 1) {
+            issues.push("ordered_table_bad_index_sequence");
+            break;
+        }
+    }
+    return issues;
+}

package/dist/ofs/enricher.d.ts

@@ -1,6 +1,16 @@
-import type { OutputFormatSpec } from "../types.js";
+import { OutputFormatSpec } from "../types.js";
+import { StrictnessOptions } from "../strictness/types.js";
 /**
- * Generate minimal, feature-driven LLM guidance from an OutputFormatSpec.
- * Only includes rules for features actually used in the spec.
+ * 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 declare function enrichInstructions(spec: OutputFormatSpec): string;
+export declare function buildMarkdownGuidance(spec: OutputFormatSpec, strict: StrictnessOptions, opts?: {
+    includeNoneRule?: "auto" | "always" | "never";
+    includeListRules?: "auto" | "always" | "never";
+    includeTableRules?: "auto" | "always" | "never";
+    containerFence?: "markdown" | "flexmd";
+}): string;
+/**
+ * @deprecated Use buildMarkdownGuidance
+ */
+export declare function enrichInstructions(spec: OutputFormatSpec, strict: StrictnessOptions): string;

package/dist/ofs/enricher.js

@@ -1,29 +1,77 @@
 /**
- * Generate minimal, feature-driven LLM guidance from an OutputFormatSpec.
- * Only includes rules for features actually used in the spec.
+ * 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 enrichInstructions(spec) {
+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 = [];
-    if (spec.emptySectionValue) {
-        lines.push(`If a section is empty, write \`${spec.emptySectionValue}\`.`);
+    // 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}`);
     }
-    const hasList = spec.sections.some(s => s.kind === "list");
-    const hasOrderedList = spec.sections.some(s => s.kind === "ordered_list");
-    const hasTable = spec.tables.length > 0;
-    const hasOrderedTable = spec.tables.some(t => t.kind === "ordered_table");
-    if (hasList) {
-        lines.push("List sections must use '-' bullets (nested allowed).");
+    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("");
     }
-    if (hasOrderedList) {
-        lines.push("Ordered-list sections must use numbered items (nested allowed).");
+    // 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("");
     }
-    if (hasTable) {
-        lines.push("Tables must be Markdown pipe tables with the specified columns.");
+    // 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 (hasOrderedTable) {
-        lines.push("Ordered tables must add a first column named '#' with rows numbered 1..N.");
+    if (level >= 3) {
+        lines.push("Do not return JSON as the response format.");
     }
-    if (lines.length === 0)
-        return "";
-    return "Rules:\n" + lines.map(l => `- ${l}`).join("\n") + "\n";
+    return lines.join("\n").trim();
+}
+/**
+ * @deprecated Use buildMarkdownGuidance
+ */
+export function enrichInstructions(spec, strict) {
+    return buildMarkdownGuidance(spec, strict);
 }

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

@@ -1,21 +1,9 @@
 import type { OutputFormatSpec } from "../types.js";
 /**
  * Parse an Output Format Spec block from Markdown.
- *
- * Expected format:
- * ## Output format (Markdown)
- * Include these sections somewhere (order does not matter):
- *
- * - Short answer — prose
- * - Long answer — prose
- * - Reasoning — ordered list
- * - Assumptions — list
- *
- * Tables (only if needed):
- * - (property1, property2, property3 — table)
- * - (property1, property2, property3 — ordered table, by property2)
- *
- * Empty sections:
- * - If a section is empty, write `None`.
  */
-export declare function parseOutputFormatSpec(md: string): OutputFormatSpec;
+export interface ParseOfsOptions {
+    headingRegex?: RegExp;
+    allowDelimiterFallbacks?: boolean;
+}
+export declare function parseOutputFormatSpec(md: string, opts?: ParseOfsOptions): OutputFormatSpec | null;