flex-md 1.1.0 → 3.0.0

package/dist/extract/extract.js

@@ -0,0 +1,50 @@
+import { parseHeadingsAndSections, extractBullets, normalizeName } from "../md/parse.js";
+/**
+ * Extracts sections, lists, and tables from Markdown based on the OFS.
+ */
+export function extractFromMarkdown(md, spec) {
+    const parsed = parseHeadingsAndSections(md);
+    const sectionsByName = {};
+    const tables = [];
+    const specMap = new Map(spec.sections.map(s => [normalizeName(s.name), s]));
+    for (const p of parsed) {
+        const norm = normalizeName(p.heading.name);
+        const sSpec = specMap.get(norm);
+        if (sSpec) {
+            const body = p.body.trim();
+            let list;
+            if (sSpec.kind === "list" || sSpec.kind === "ordered_list") {
+                const bullets = extractBullets(body);
+                if (bullets.length > 0) {
+                    list = {
+                        kind: "list",
+                        ordered: sSpec.kind === "ordered_list",
+                        items: bullets.map(b => ({ text: b, children: [] }))
+                    };
+                }
+            }
+            // Merge if duplicate heading (standard policy for extraction)
+            if (sectionsByName[sSpec.name]) {
+                sectionsByName[sSpec.name].md += "\n\n" + body;
+                if (list && sectionsByName[sSpec.name].list) {
+                    sectionsByName[sSpec.name].list.items.push(...list.items);
+                }
+            }
+            else {
+                sectionsByName[sSpec.name] = {
+                    nodeKey: norm,
+                    nodeLevel: p.heading.level,
+                    md: body,
+                    list
+                };
+            }
+        }
+    }
+    // Table extraction logic (simplified for now)
+    // In a full impl, we'd search section bodies for tables.
+    return {
+        outline: { type: "md_outline", nodes: [] }, // Simplified outline
+        sectionsByName,
+        tables
+    };
+}

package/dist/extract/types.d.ts

@@ -0,0 +1,11 @@
+import type { MdOutline, ParsedList, ParsedTable } from "../types.js";
+export interface ExtractedResult {
+    outline: MdOutline;
+    sectionsByName: Record<string, {
+        nodeKey: string;
+        nodeLevel: number;
+        md: string;
+        list?: ParsedList;
+    }>;
+    tables: ParsedTable[];
+}

package/dist/extract/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,4 +1,14 @@
 export * from "./types.js";
-export { parseFlexMd } from "./parser.js";
-export { stringifyFlexMd } from "./stringify.js";
-export { validateFlexMd } from "./validator.js";
+export * from "./strictness/types.js";
+export * from "./md/parse.js";
+export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
+export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { extractFromMarkdown } from "./extract/extract.js";
+export { processResponseMarkdown } from "./strictness/processor.js";
+export { parseIssuesEnvelope, buildIssuesEnvelope, buildIssuesEnvelopeAuto } from "./ofs/issuesEnvelope.js";
+export { detectResponseKind } from "./pipeline/kind.js";
+export { repairToMarkdownLevel } from "./pipeline/repair.js";
+export { enforceFlexMd } from "./pipeline/enforce.js";
+export * from "./detect/json/index.js";

package/dist/index.js

@@ -1,4 +1,21 @@
+// Core SFMD Types
 export * from "./types.js";
-export { parseFlexMd } from "./parser.js";
-export { stringifyFlexMd } from "./stringify.js";
-export { validateFlexMd } from "./validator.js";
+export * from "./strictness/types.js";
+// Shared MD Parsing
+export * from "./md/parse.js";
+// Output Format Spec (OFS)
+export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
+export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+// Validation & Extraction
+export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { extractFromMarkdown } from "./extract/extract.js";
+// Processor & Fallback
+export { processResponseMarkdown } from "./strictness/processor.js";
+export { parseIssuesEnvelope, buildIssuesEnvelope, buildIssuesEnvelopeAuto } from "./ofs/issuesEnvelope.js";
+// Pipeline
+export { detectResponseKind } from "./pipeline/kind.js";
+export { repairToMarkdownLevel } from "./pipeline/repair.js";
+export { enforceFlexMd } from "./pipeline/enforce.js";
+// JSON Detection
+export * from "./detect/json/index.js";

package/dist/issues/build.d.ts

@@ -0,0 +1,26 @@
+import type { StrictnessOptions } from "../strictness/types.js";
+export type IssuesStatusCode = "missing_input" | "unclear_instructions" | "invalid_format" | "unsupported" | (string & {});
+export interface IssueItem {
+    issue: string;
+    path?: string;
+    expected?: string;
+    got?: string;
+    hint?: string;
+    [k: string]: string | undefined;
+}
+export interface BuildIssuesEnvelopeInput {
+    status: "error" | "partial";
+    code: IssuesStatusCode;
+    message: string;
+    issues: IssueItem[];
+    missingInputs?: string[];
+    clarificationsNeeded?: string[];
+    /** If provided, wraps output in a single container fence when strictness requires it. */
+    strictness?: StrictnessOptions;
+    /** Override fence language: "markdown" | "flexmd" (defaults from strictness.container) */
+    fence?: "markdown" | "flexmd";
+}
+/**
+ * Build a Markdown-only issues envelope.
+ */
+export declare function buildIssuesEnvelope(input: BuildIssuesEnvelopeInput): string;

package/dist/issues/build.js

@@ -0,0 +1,62 @@
+import { strictnessDefaults } from "../strictness/types.js";
+/**
+ * Build a Markdown-only issues envelope.
+ */
+export function buildIssuesEnvelope(input) {
+    const strict = input.strictness ? { ...strictnessDefaults(input.strictness.level), ...input.strictness } : undefined;
+    const fence = input.fence ?? resolveFence(strict);
+    const lines = [];
+    lines.push(`## Status`);
+    lines.push(`- status: ${input.status}`);
+    lines.push(`- code: ${input.code}`);
+    lines.push(`- message: ${input.message}`);
+    lines.push(``);
+    if (input.missingInputs && input.missingInputs.length) {
+        lines.push(`## Missing inputs`);
+        for (const mi of input.missingInputs)
+            lines.push(`- ${mi}`);
+        lines.push(``);
+    }
+    if (input.clarificationsNeeded && input.clarificationsNeeded.length) {
+        lines.push(`## Clarifications needed`);
+        for (const q of input.clarificationsNeeded)
+            lines.push(`- ${q}`);
+        lines.push(``);
+    }
+    lines.push(`## Issues`);
+    if (!input.issues.length) {
+        lines.push(`- issue: none`);
+    }
+    else {
+        for (const it of input.issues) {
+            lines.push(`- issue: ${it.issue}`);
+            emitField(lines, "path", it.path);
+            emitField(lines, "expected", it.expected);
+            emitField(lines, "got", it.got);
+            emitField(lines, "hint", it.hint);
+            for (const [k, v] of Object.entries(it)) {
+                if (k === "issue" || k === "path" || k === "expected" || k === "got" || k === "hint")
+                    continue;
+                emitField(lines, k, v);
+            }
+        }
+    }
+    let md = lines.join("\n").trimEnd() + "\n";
+    if (strict && strict.level >= 2) {
+        const lang = (fence === "flexmd") ? "flexmd" : "markdown";
+        md = `\`\`\`${lang}\n${md}\`\`\`\n`;
+    }
+    return md;
+}
+function emitField(lines, key, value) {
+    if (value == null || value === "")
+        return;
+    lines.push(`  ${key}: ${value}`);
+}
+function resolveFence(strict) {
+    if (!strict)
+        return "markdown";
+    if (strict.container === "flexmd_fence")
+        return "flexmd";
+    return "markdown";
+}

package/dist/md/lists.d.ts

@@ -0,0 +1,14 @@
+export interface ListItem {
+    text: string;
+    index?: number;
+    children: ListItem[];
+}
+export interface ParsedList {
+    kind: "list";
+    ordered: boolean;
+    items: ListItem[];
+}
+/**
+ * Parses a flat list segment from Markdown into a nested structure.
+ */
+export declare function parseNestedList(sectionMd: string): ParsedList | null;

package/dist/md/lists.js

@@ -0,0 +1,33 @@
+/**
+ * Parses a flat list segment from Markdown into a nested structure.
+ */
+export function parseNestedList(sectionMd) {
+    const lines = sectionMd.split("\n");
+    const listLines = lines
+        .map(l => ({ raw: l, indent: (l.match(/^\s*/)?.[0].length ?? 0) }))
+        .filter(x => /^\s*(-\s+|\d+\.\s+)/.test(x.raw));
+    if (!listLines.length)
+        return null;
+    const ordered = listLines.some(x => /^\s*\d+\.\s+/.test(x.raw));
+    const root = [];
+    const stack = [];
+    for (const { raw, indent } of listLines) {
+        const mO = raw.match(/^\s*(\d+)\.\s+(.*)$/);
+        const mU = raw.match(/^\s*-\s+(.*)$/);
+        const text = (mO?.[2] ?? mU?.[1] ?? "").trim();
+        const item = { text, children: [] };
+        if (mO)
+            item.index = Number(mO[1]);
+        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/md/match.d.ts

@@ -0,0 +1,12 @@
+import type { MdNode, MdOutline } from "../types.js";
+export interface MatchedSection {
+    name: string;
+    nodes: MdNode[];
+    chosen: MdNode[];
+    mergedContent: string;
+}
+/**
+ * Matches sections from the outline against required section names.
+ * Supports merging multiple nodes of the same name and selecting highest-level matches.
+ */
+export declare function matchSections(outline: MdOutline, sectionNames: string[], strategy?: "merge" | "first"): Map<string, MatchedSection>;

package/dist/md/match.js

@@ -0,0 +1,44 @@
+/**
+ * Matches sections from the outline against required section names.
+ * Supports merging multiple nodes of the same name and selecting highest-level matches.
+ */
+export function matchSections(outline, sectionNames, strategy = "merge") {
+    const normalizedTargets = new Map(sectionNames.map(n => [norm(n), n]));
+    const found = new Map();
+    walk(outline.nodes, (node) => {
+        const k = norm(node.title);
+        if (normalizedTargets.has(k)) {
+            if (!found.has(k))
+                found.set(k, []);
+            found.get(k).push(node);
+        }
+    });
+    const res = new Map();
+    for (const [nk, originalName] of normalizedTargets.entries()) {
+        const nodes = found.get(nk) ?? [];
+        if (!nodes.length)
+            continue;
+        // choose highest-level (smallest level number)
+        const minLevel = Math.min(...nodes.map(n => n.level));
+        const top = nodes.filter(n => n.level === minLevel);
+        let chosen;
+        if (strategy === "first") {
+            chosen = [top[0]];
+        }
+        else {
+            chosen = top; // merge same-level matches
+        }
+        const merged = chosen.map(n => n.content_md).join("\n").trimEnd() + "\n";
+        res.set(originalName, { name: originalName, nodes, chosen, mergedContent: merged });
+    }
+    return res;
+}
+function walk(nodes, fn) {
+    for (const n of nodes) {
+        fn(n);
+        walk(n.children, fn);
+    }
+}
+function norm(s) {
+    return s.trim().replace(/[:\-–—]\s*$/, "").trim().toLowerCase();
+}

package/dist/md/outline.d.ts

@@ -0,0 +1,6 @@
+import type { MdOutline } from "../types.js";
+/**
+ * Builds a nested outline tree from Markdown headings.
+ * Supports any heading level and captures content between headings.
+ */
+export declare function buildOutline(md: string): MdOutline;

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

@@ -0,0 +1,16 @@
+import { OutputFormatSpec } from "../types.js";
+import { StrictnessOptions } from "../strictness/types.js";
+/**
+ * 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 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;