flex-md 1.0.0 → 2.0.0

package/dist/detection/extractor.js

@@ -0,0 +1,54 @@
+import { detectObjects } from "./detector.js";
+import { parseFlexMd } from "../parser.js";
+/**
+ * Parse any text and extract all FlexMD documents and Markdown snippets.
+ */
+export function parseAny(text) {
+    const detected = detectObjects(text);
+    const flexDocs = [];
+    const markdownSnippets = [];
+    for (const obj of detected) {
+        if (obj.kind === "flexmd_fence" && obj.inner) {
+            // Parse fenced FlexMD
+            try {
+                const doc = parseFlexMd(obj.inner);
+                flexDocs.push(doc);
+            }
+            catch {
+                // Parse failed, treat as markdown snippet
+                markdownSnippets.push(obj.inner);
+            }
+        }
+        else if (obj.kind === "flexdoc_json_fence" && obj.inner) {
+            // Parse JSON FlexDocument
+            try {
+                const doc = JSON.parse(obj.inner);
+                flexDocs.push(doc);
+            }
+            catch {
+                // Parse failed, skip
+            }
+        }
+        else if (obj.kind === "raw_flexmd") {
+            // Parse raw FlexMD
+            try {
+                const doc = parseFlexMd(obj.raw);
+                flexDocs.push(doc);
+            }
+            catch {
+                // Parse failed, treat as markdown snippet
+                markdownSnippets.push(obj.raw);
+            }
+        }
+    }
+    // Calculate remainder (text not covered by detected objects)
+    let remainder = text;
+    for (const obj of detected) {
+        remainder = remainder.replace(obj.raw, "");
+    }
+    return {
+        flexDocs,
+        markdownSnippets,
+        remainder: remainder.trim()
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,18 @@
 export * from "./types.js";
 export { parseFlexMd } from "./parser.js";
 export { stringifyFlexMd } from "./stringify.js";
+export { validateFlexMd } from "./validator.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";

package/dist/index.js

@@ -1,3 +1,20 @@
+// Layer A - FlexMD Frames
 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 { 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";

package/dist/ofs/enricher.d.ts

@@ -0,0 +1,6 @@
+import type { OutputFormatSpec } from "../types.js";
+/**
+ * Generate minimal, feature-driven LLM guidance from an OutputFormatSpec.
+ * Only includes rules for features actually used in the spec.
+ */
+export declare function enrichInstructions(spec: OutputFormatSpec): string;

package/dist/ofs/enricher.js

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

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/parser.d.ts

@@ -0,0 +1,21 @@
+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;

package/dist/ofs/parser.js

@@ -0,0 +1,64 @@
+/**
+ * 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 function parseOutputFormatSpec(md) {
+    const sections = [];
+    const tables = [];
+    let emptySectionValue;
+    const lines = md.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Parse section definitions: "- Section name — kind"
+        const sectionMatch = trimmed.match(/^-\s+(.+?)\s+[—–-]\s+(prose|list|ordered list)(.*)$/i);
+        if (sectionMatch) {
+            const name = sectionMatch[1].trim();
+            const kindStr = sectionMatch[2].trim().toLowerCase().replace(/\s+/g, "_");
+            const kind = kindStr;
+            const hint = sectionMatch[3]?.trim();
+            sections.push({ name, kind, hint: hint || undefined });
+            continue;
+        }
+        // Parse table definitions: "- (col1, col2, col3 — table)" or "- (col1, col2 — ordered table, by col1)"
+        const tableMatch = trimmed.match(/^-\s+\(([^)]+)\s+[—–-]\s+(table|ordered table)(?:,\s*by\s+([^)]+))?\)$/i);
+        if (tableMatch) {
+            const columnsStr = tableMatch[1].trim();
+            const columns = columnsStr.split(",").map(c => c.trim());
+            const kindStr = tableMatch[2].trim().toLowerCase().replace(/\s+/g, "_");
+            const kind = kindStr;
+            const by = tableMatch[3]?.trim();
+            tables.push({ columns, kind, by });
+            continue;
+        }
+        // Parse empty section value: "If a section is empty, write `None`."
+        const emptyMatch = trimmed.match(/If a section is empty.*?`([^`]+)`/i);
+        if (emptyMatch) {
+            emptySectionValue = emptyMatch[1];
+            continue;
+        }
+    }
+    return {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections,
+        tablesOptional: true,
+        tables,
+        emptySectionValue
+    };
+}

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,30 @@
+/**
+ * Convert an OutputFormatSpec to canonical Markdown format.
+ */
+export function stringifyOutputFormatSpec(spec) {
+    const parts = [];
+    parts.push("## Output format (Markdown)\n");
+    parts.push("Include these sections somewhere (order does not matter):\n\n");
+    // Sections
+    for (const section of spec.sections) {
+        const kindStr = section.kind.replace(/_/g, " ");
+        const hint = section.hint ? ` ${section.hint}` : "";
+        parts.push(`- ${section.name} — ${kindStr}${hint}\n`);
+    }
+    // Tables
+    if (spec.tables.length > 0) {
+        parts.push("\nTables (only if needed):\n");
+        for (const table of spec.tables) {
+            const kindStr = table.kind.replace(/_/g, " ");
+            const cols = table.columns.join(", ");
+            const byStr = table.by ? `, by ${table.by}` : "";
+            parts.push(`- (${cols} — ${kindStr}${byStr})\n`);
+        }
+    }
+    // Empty section value
+    if (spec.emptySectionValue) {
+        parts.push("\nEmpty sections:\n");
+        parts.push(`- If a section is empty, write \`${spec.emptySectionValue}\`.\n`);
+    }
+    return parts.join("");
+}

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;

package/dist/outline/builder.js

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

package/dist/outline/renderer.d.ts

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

package/dist/outline/renderer.js

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

package/dist/parser.js

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

package/dist/parsers/lists.d.ts

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