flex-md 2.0.0 → 3.1.0

package/dist/detect/json/detectPresence.js

@@ -0,0 +1,191 @@
+const RX_JSON_FENCE = /```json\s*\n([\s\S]*?)\n```/gi;
+const RX_JSON_MARKER = /(BEGIN_JSON|BEGIN\s+JSON)\s*\n([\s\S]*?)\n(END_JSON|END\s+JSON)/gi;
+// Very conservative raw JSON: must be only whitespace + object/array + whitespace
+const RX_RAW_JSON = /^\s*(\{[\s\S]*\}|\[[\s\S]*\])\s*$/;
+// Inline candidate finder
+const RX_INLINE_CANDIDATE = /(\{|\[)/g;
+export function detectJsonContainers(md) {
+    const fences = [];
+    const markers = [];
+    RX_JSON_FENCE.lastIndex = 0;
+    RX_JSON_MARKER.lastIndex = 0;
+    let m;
+    while ((m = RX_JSON_FENCE.exec(md)) !== null) {
+        fences.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            kind: "fence",
+            snippet: preview(m[0]),
+        });
+    }
+    while ((m = RX_JSON_MARKER.exec(md)) !== null) {
+        markers.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            kind: "marker",
+            snippet: preview(m[0]),
+        });
+    }
+    return {
+        hasJsonFence: fences.length > 0,
+        hasJsonMarkers: markers.length > 0,
+        fences,
+        markers,
+    };
+}
+export function detectJsonPresence(text, opts) {
+    const spans = [];
+    const kinds = new Set();
+    // 1) fenced json blocks
+    let m;
+    RX_JSON_FENCE.lastIndex = 0;
+    while ((m = RX_JSON_FENCE.exec(text)) !== null) {
+        kinds.add("fenced_json");
+        spans.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            kind: "fence",
+            snippet: preview(m[0]),
+        });
+    }
+    // 2) BEGIN_JSON / END_JSON
+    RX_JSON_MARKER.lastIndex = 0;
+    while ((m = RX_JSON_MARKER.exec(text)) !== null) {
+        kinds.add("fenced_json");
+        spans.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            kind: "marker",
+            snippet: preview(m[0]),
+        });
+    }
+    // 3) raw json (standalone)
+    if (RX_RAW_JSON.test(text) && looksLikeJson(text)) {
+        kinds.add("raw_json");
+        spans.push({ start: 0, end: text.length, kind: "raw", snippet: preview(text) });
+    }
+    else {
+        // 4) inline json-ish occurrences (best effort)
+        const inlineSpans = findInlineJsonishSpans(text);
+        if (inlineSpans.length) {
+            kinds.add("inline_json");
+            for (const s of inlineSpans)
+                spans.push(s);
+        }
+    }
+    const present = kinds.size > 0;
+    // Optional parse
+    const parse = !!opts?.parse;
+    if (!parse || !present) {
+        return { present, kinds: Array.from(kinds), spans };
+    }
+    const maxParses = opts?.maxParses ?? 3;
+    const parsedValues = [];
+    const errors = [];
+    const parseCandidates = spans
+        .map((s, i) => ({ s, i }))
+        .filter(x => x.s.kind === "fence" || x.s.kind === "raw" || x.s.kind === "inline")
+        .slice(0, maxParses);
+    for (const { s, i } of parseCandidates) {
+        const content = extractJsonText(text, s);
+        try {
+            parsedValues.push(JSON.parse(content));
+        }
+        catch (e) {
+            errors.push({ spanIndex: i, message: String(e?.message ?? e) });
+            if (looksLikeJson(content))
+                kinds.add("json_like");
+        }
+    }
+    return {
+        present,
+        kinds: Array.from(kinds),
+        spans,
+        parsed: {
+            ok: errors.length === 0 && parsedValues.length > 0,
+            values: parsedValues,
+            errors: errors.length ? errors : undefined,
+        },
+    };
+}
+function extractJsonText(full, span) {
+    const slice = full.slice(span.start, span.end);
+    if (span.kind === "fence") {
+        const m = slice.match(/^```json\s*\n([\s\S]*?)\n```$/i);
+        if (m)
+            return m[1] ?? "";
+    }
+    if (span.kind === "marker") {
+        const m = slice.match(/(BEGIN_JSON|BEGIN\s+JSON)\s*\n([\s\S]*?)\n(END_JSON|END\s+JSON)/i);
+        if (m)
+            return m[2] ?? "";
+    }
+    return slice;
+}
+function looksLikeJson(s) {
+    const t = s.trim();
+    if (!t)
+        return false;
+    if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]")))
+        return true;
+    return false;
+}
+function findInlineJsonishSpans(text) {
+    const spans = [];
+    const maxLen = 5000;
+    const masked = maskNonJsonCodeFences(text);
+    let m;
+    RX_INLINE_CANDIDATE.lastIndex = 0;
+    while ((m = RX_INLINE_CANDIDATE.exec(masked)) !== null) {
+        const start = m.index;
+        const open = masked[start];
+        const close = open === "{" ? "}" : "]";
+        let depth = 0;
+        let end = -1;
+        for (let i = start; i < Math.min(masked.length, start + maxLen); i++) {
+            const ch = masked[i];
+            if (ch === open)
+                depth++;
+            else if (ch === close) {
+                depth--;
+                if (depth === 0) {
+                    end = i + 1;
+                    break;
+                }
+            }
+        }
+        if (end > start) {
+            const snippet = text.slice(start, Math.min(end, start + 300));
+            if (snippet.trim().length >= 5) {
+                spans.push({ start, end, kind: "inline", snippet: preview(text.slice(start, end)) });
+            }
+            RX_INLINE_CANDIDATE.lastIndex = end;
+        }
+    }
+    return squashOverlaps(spans);
+}
+function maskNonJsonCodeFences(text) {
+    const rx = /```(\w+)?\s*\n([\s\S]*?)\n```/g;
+    return text.replace(rx, (full, lang) => {
+        const l = String(lang ?? "").toLowerCase();
+        if (l === "json")
+            return full;
+        return " ".repeat(full.length);
+    });
+}
+function squashOverlaps(spans) {
+    spans.sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start));
+    const out = [];
+    let last = null;
+    for (const s of spans) {
+        if (!last || s.start >= last.end) {
+            out.push(s);
+            last = s;
+        }
+    }
+    return out;
+}
+function preview(s, n = 160) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}

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

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

package/dist/detect/json/index.js

@@ -0,0 +1,12 @@
+import { detectJsonIntent } from "./detectIntent.js";
+import { detectJsonContainers, detectJsonPresence } from "./detectPresence.js";
+export * from "./types.js";
+export { detectJsonIntent } from "./detectIntent.js";
+export { detectJsonContainers, detectJsonPresence } from "./detectPresence.js";
+export function detectJsonAll(textOrMd, opts) {
+    return {
+        intent: detectJsonIntent(textOrMd),
+        containers: detectJsonContainers(textOrMd),
+        presence: detectJsonPresence(textOrMd, { parse: !!opts?.parseJson }),
+    };
+}

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

@@ -0,0 +1,43 @@
+export type JsonIntent = "none" | "soft" | "hard" | "schema" | "tooling";
+export type JsonPresenceKind = "none" | "fenced_json" | "raw_json" | "inline_json" | "json_like";
+export interface JsonSpan {
+    start: number;
+    end: number;
+    kind: "fence" | "raw" | "inline" | "marker";
+    snippet: string;
+}
+export interface DetectJsonPresenceResult {
+    present: boolean;
+    kinds: JsonPresenceKind[];
+    spans: JsonSpan[];
+    parsed?: {
+        ok: boolean;
+        values: unknown[];
+        errors?: Array<{
+            spanIndex: number;
+            message: string;
+        }>;
+    };
+}
+export interface DetectJsonContainersResult {
+    hasJsonFence: boolean;
+    hasJsonMarkers: boolean;
+    fences: JsonSpan[];
+    markers: JsonSpan[];
+}
+export interface DetectJsonIntentResult {
+    intent: JsonIntent;
+    signals: Array<{
+        type: "pattern";
+        value: string;
+        strength: "soft" | "hard";
+        start?: number;
+        end?: number;
+    }>;
+    confidence: number;
+}
+export interface DetectJsonAllResult {
+    intent: DetectJsonIntentResult;
+    containers: DetectJsonContainersResult;
+    presence: DetectJsonPresenceResult;
+}

package/dist/detect/json/types.js

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

package/dist/extract/extract.d.ts

@@ -0,0 +1,5 @@
+import { OutputFormatSpec, ExtractedResult } from "../types.js";
+/**
+ * Extracts sections, lists, and tables from Markdown based on the OFS.
+ */
+export declare function extractFromMarkdown(md: string, spec: OutputFormatSpec): ExtractedResult;

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,18 +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 { enrichInstructions } from "./ofs/enricher.js";
-export { validateOutput } from "./ofs/validator.js";
-export type { OfsValidationResult } from "./ofs/validator.js";
-export { extractOutput } from "./ofs/extractor.js";
-export type { ExtractOptions } from "./ofs/extractor.js";
-export { buildOutline, slugify } from "./outline/builder.js";
-export { renderOutline } from "./outline/renderer.js";
-export { parseList } from "./parsers/lists.js";
-export { parsePipeTable, extractAllTables } from "./parsers/tables.js";
-export { detectObjects } from "./detection/detector.js";
-export { parseAny } from "./detection/extractor.js";
-export type { ParseAnyResult } from "./detection/extractor.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,20 +1,21 @@
-// Layer A - FlexMD Frames
+// Core SFMD Types
 export * from "./types.js";
-export { parseFlexMd } from "./parser.js";
-export { stringifyFlexMd } from "./stringify.js";
-export { validateFlexMd } from "./validator.js";
-// Layer B - Output Format Spec (OFS)
+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 { enrichInstructions } from "./ofs/enricher.js";
-export { validateOutput } from "./ofs/validator.js";
-export { extractOutput } from "./ofs/extractor.js";
-// Outline & Tree
-export { buildOutline, slugify } from "./outline/builder.js";
-export { renderOutline } from "./outline/renderer.js";
-// Parsers
-export { parseList } from "./parsers/lists.js";
-export { parsePipeTable, extractAllTables } from "./parsers/tables.js";
-// Layer C - Detection & Extraction
-export { detectObjects } from "./detection/detector.js";
-export { parseAny } from "./detection/extractor.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;