flex-md 1.1.0 → 3.0.0

package/dist/validate/validate.js

@@ -0,0 +1,308 @@
+import { extractFencedBlocks, parseHeadingsAndSections, normalizeName, isIssuesEnvelopeCheck } from "../md/parse.js";
+function enforcementToSeverity(e) {
+    if (e === "ignore")
+        return null;
+    return e === "warn" ? "warn" : "error";
+}
+function defaultPolicy(level) {
+    return {
+        missingSection: level >= 1 ? "error" : "ignore",
+        emptyRequiredSection: level >= 1 ? "error" : "ignore",
+        wrongSectionKind: level >= 3 ? "error" : "ignore",
+        containerMissing: level >= 2 ? "error" : "ignore",
+        containerMultiple: level >= 2 ? "error" : "ignore",
+        containerOutsideText: level >= 2 ? "error" : "ignore",
+        duplicateSection: level >= 1 ? "warn" : "ignore",
+        malformedTable: level >= 3 ? "error" : "ignore",
+        malformedOrderedTable: level >= 3 ? "error" : "ignore",
+        noneIsAcceptableContent: true,
+    };
+}
+function addIssue(issues, policyLevel, issue) {
+    const sev = enforcementToSeverity(policyLevel);
+    if (!sev)
+        return;
+    issues.push({ ...issue, severity: sev });
+}
+function isRequiredSection(spec, level) {
+    if (typeof spec.required === "boolean")
+        return spec.required;
+    return level >= 1;
+}
+function stripToWorkingMarkdown(input, level) {
+    if (level < 2)
+        return { working: input, container: null };
+    const fences = extractFencedBlocks(input);
+    if (fences.length === 1) {
+        const f = fences[0];
+        return { working: f.content, container: { fence: f } };
+    }
+    return { working: input, container: null };
+}
+export function validateMarkdownAgainstOfs(input, spec, level, policyOverride) {
+    const policy = { ...defaultPolicy(level), ...(policyOverride ?? {}) };
+    const issues = [];
+    const fencesAll = extractFencedBlocks(input);
+    if (level === 0) {
+        const env = isIssuesEnvelopeCheck(input);
+        return {
+            ok: true,
+            level,
+            issues: [],
+            stats: {
+                detectedKind: env.isIssuesEnvelope ? "issues" : "markdown",
+                sectionCount: 0,
+                missingRequired: [],
+                duplicates: [],
+                container: { fenceCount: fencesAll.length, hasOutsideText: false, fenceLangs: fencesAll.map(f => f.lang) },
+            },
+        };
+    }
+    const env = isIssuesEnvelopeCheck(input);
+    if (env.isIssuesEnvelope) {
+        issues.push({
+            code: "ISSUES_ENVELOPE_PRESENT",
+            severity: "error",
+            message: "Issues envelope present (model did not return a normal answer).",
+        });
+        return {
+            ok: false,
+            level,
+            issues,
+            stats: {
+                detectedKind: "issues",
+                sectionCount: Object.keys(env.sections).length,
+                missingRequired: [],
+                duplicates: [],
+                container: { fenceCount: fencesAll.length, hasOutsideText: false, fenceLangs: fencesAll.map(f => f.lang) },
+            },
+        };
+    }
+    const fenceLangs = fencesAll.map(f => f.lang || "(none)");
+    let hasOutsideText = false;
+    if (level >= 2) {
+        if (fencesAll.length === 0) {
+            addIssue(issues, policy.containerMissing, {
+                code: "CONTAINER_MISSING",
+                message: "L2+ requires a single fenced ```markdown block (none found).",
+            });
+        }
+        else if (fencesAll.length > 1) {
+            addIssue(issues, policy.containerMultiple, {
+                code: "CONTAINER_MULTIPLE",
+                message: `L2+ requires a single fenced block (found ${fencesAll.length}).`,
+            });
+        }
+        else {
+            const f = fencesAll[0];
+            const before = input.slice(0, f.start).trim();
+            const after = input.slice(f.end).trim();
+            hasOutsideText = before.length > 0 || after.length > 0;
+            if (hasOutsideText) {
+                addIssue(issues, policy.containerOutsideText, {
+                    code: "CONTAINER_OUTSIDE_TEXT",
+                    message: "Text exists outside the single fenced block (L2+ requires nothing outside).",
+                });
+            }
+        }
+    }
+    const { working } = stripToWorkingMarkdown(input, level);
+    const parsed = parseHeadingsAndSections(working);
+    const specByNorm = new Map();
+    for (const s of spec.sections)
+        specByNorm.set(normalizeName(s.name), s);
+    const occurrences = new Map();
+    const bodiesByNorm = {};
+    for (const sec of parsed) {
+        if (!specByNorm.has(sec.heading.norm))
+            continue;
+        occurrences.set(sec.heading.norm, (occurrences.get(sec.heading.norm) ?? 0) + 1);
+        bodiesByNorm[sec.heading.norm] = bodiesByNorm[sec.heading.norm] ?? [];
+        bodiesByNorm[sec.heading.norm].push(sec.body.trim());
+    }
+    const missingRequired = [];
+    for (const s of spec.sections) {
+        const req = isRequiredSection(s, level);
+        if (!req)
+            continue;
+        const norm = normalizeName(s.name);
+        const count = occurrences.get(norm) ?? 0;
+        if (count === 0) {
+            missingRequired.push(s.name);
+            addIssue(issues, policy.missingSection, {
+                code: "MISSING_SECTION",
+                message: `Missing required section: "${s.name}"`,
+                sectionName: s.name,
+            });
+        }
+    }
+    const noneValue = spec.emptySectionValue ?? "None";
+    for (const s of spec.sections) {
+        const req = isRequiredSection(s, level);
+        if (!req)
+            continue;
+        const norm = normalizeName(s.name);
+        const bodies = bodiesByNorm[norm] ?? [];
+        if (!bodies.length)
+            continue;
+        const allEmpty = bodies.every(b => b.trim().length === 0);
+        const allNone = bodies.every(b => normalizeName(b) === normalizeName(noneValue));
+        const emptyByPolicy = allEmpty || (!policy.noneIsAcceptableContent && allNone);
+        if (emptyByPolicy) {
+            addIssue(issues, policy.emptyRequiredSection, {
+                code: "EMPTY_REQUIRED_SECTION",
+                message: `Empty required section: "${s.name}"`,
+                sectionName: s.name,
+            });
+        }
+    }
+    const duplicates = [];
+    for (const [norm, count] of occurrences.entries()) {
+        if (count > 1) {
+            const name = specByNorm.get(norm).name;
+            duplicates.push(name);
+            addIssue(issues, policy.duplicateSection, {
+                code: "DUPLICATE_SECTION",
+                message: `Duplicate section heading: "${name}" (appears ${count} times)`,
+                sectionName: name,
+            });
+        }
+    }
+    if (level >= 3) {
+        for (const s of spec.sections) {
+            const norm = normalizeName(s.name);
+            const bodies = bodiesByNorm[norm] ?? [];
+            if (!bodies.length)
+                continue;
+            const kind = s.kind ?? "text";
+            for (const body of bodies) {
+                const b = body.trim();
+                if (normalizeName(b) === normalizeName(noneValue))
+                    continue;
+                if (kind === "text")
+                    continue;
+                if (kind === "list") {
+                    const ok = /^\s*[-*]\s+/m.test(b);
+                    if (!ok) {
+                        addIssue(issues, policy.wrongSectionKind, {
+                            code: "WRONG_SECTION_KIND",
+                            message: `Section "${s.name}" must be a bullet list (use "-" bullets).`,
+                            sectionName: s.name,
+                        });
+                    }
+                }
+                else if (kind === "ordered_list") {
+                    const ok = /^\s*\d+\.\s+/m.test(b);
+                    if (!ok) {
+                        addIssue(issues, policy.wrongSectionKind, {
+                            code: "WRONG_SECTION_KIND",
+                            message: `Section "${s.name}" must be an ordered list (use "1.", "2.", …).`,
+                            sectionName: s.name,
+                        });
+                    }
+                }
+                else if (kind === "table" || kind === "ordered_table") {
+                    const table = findPipeTable(b);
+                    if (!table) {
+                        addIssue(issues, policy.malformedTable, {
+                            code: "MALFORMED_TABLE",
+                            message: `Section "${s.name}" must be a Markdown pipe table.`,
+                            sectionName: s.name,
+                        });
+                        continue;
+                    }
+                    const cols = (s.columns ?? []).map(c => normalizeName(c));
+                    if (cols.length) {
+                        const headerNorm = table.header.map(c => normalizeName(c));
+                        const missingCols = cols.filter(c => !headerNorm.includes(c));
+                        if (missingCols.length) {
+                            addIssue(issues, policy.malformedTable, {
+                                code: "MALFORMED_TABLE",
+                                message: `Table in section "${s.name}" is missing columns: ${missingCols.join(", ")}`,
+                                sectionName: s.name,
+                            });
+                        }
+                    }
+                    if (kind === "ordered_table") {
+                        const header0 = normalizeName(table.header[0] ?? "");
+                        if (header0 !== "#") {
+                            addIssue(issues, policy.malformedOrderedTable, {
+                                code: "MALFORMED_ORDERED_TABLE",
+                                message: `Ordered table in section "${s.name}" must include a first column named "#".`,
+                                sectionName: s.name,
+                            });
+                        }
+                        else {
+                            const nums = table.rows.map(r => (r[0] ?? "").trim()).filter(Boolean);
+                            const okSeq = nums.every((v, idx) => String(idx + 1) === v);
+                            if (!okSeq && nums.length) {
+                                addIssue(issues, policy.malformedOrderedTable, {
+                                    code: "MALFORMED_ORDERED_TABLE",
+                                    message: `Ordered table in section "${s.name}" should have sequential row numbers 1..N in column "#".`,
+                                    sectionName: s.name,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const ok = !issues.some(i => i.severity === "error");
+    return {
+        ok,
+        level,
+        issues,
+        stats: {
+            detectedKind: level >= 2 ? (fencesAll.length ? "fenced" : "markdown") : (parsed.length ? "sectioned" : "markdown"),
+            sectionCount: occurrences.size,
+            missingRequired,
+            duplicates,
+            container: {
+                fenceCount: fencesAll.length,
+                hasOutsideText,
+                fenceLangs,
+            },
+        },
+    };
+}
+function findPipeTable(body) {
+    const lines = body.split(/\r?\n/).map(l => l.trim()).filter(l => l.length > 0);
+    for (let i = 0; i < lines.length - 1; i++) {
+        const h = lines[i];
+        const sep = lines[i + 1];
+        if (!looksLikePipeRow(h))
+            continue;
+        if (!looksLikeSeparatorRow(sep))
+            continue;
+        const header = splitPipeRow(h);
+        const rows = [];
+        for (let j = i + 2; j < lines.length; j++) {
+            const r = lines[j];
+            if (!looksLikePipeRow(r))
+                break;
+            rows.push(splitPipeRow(r));
+        }
+        return { header, rows };
+    }
+    return null;
+}
+function looksLikePipeRow(line) {
+    return line.includes("|") && /[^|]/.test(line.replace(/\|/g, ""));
+}
+function looksLikeSeparatorRow(line) {
+    if (!line.includes("|"))
+        return false;
+    const cells = splitPipeRow(line);
+    if (!cells.length)
+        return false;
+    return cells.every(c => /^:?-{3,}:?$/.test(c.trim()));
+}
+function splitPipeRow(line) {
+    let s = line.trim();
+    if (s.startsWith("|"))
+        s = s.slice(1);
+    if (s.endsWith("|"))
+        s = s.slice(0, -1);
+    return s.split("|").map(c => c.trim());
+}

package/docs/mdflex-compliance.md

@@ -0,0 +1,216 @@
+Below is the **instruction spec** for the component that generates **LLM guidance** for Flex-MD compliance, by strictness level. This is written for *people writing prompts* or for your `buildPrompt(spec, strictness)` generator.
+
+Flex-MD is **Markdown**. The “levels” only change **how much structure you require and enforce**.
+
+---
+
+## Flex-MD strictness levels
+
+### L0 — Plain Markdown (minimum)
+
+Goal: get readable content with low prompt-tax.
+
+**What you tell the LLM**
+
+* “Reply in Markdown.”
+
+**What you enforce**
+
+* Nothing beyond “it’s text/Markdown”.
+* No required sections.
+
+**When to use**
+
+* Creative / exploratory answers.
+* You don’t need predictable parsing.
+
+---
+
+### L1 — Sectioned Flex-MD (human-readable + machine-extractable)
+
+Goal: ensure predictable headings exist (order doesn’t matter).
+
+**What you tell the LLM (minimal)**
+
+* “Reply in Markdown.”
+* “Include these section headings somewhere (order doesn’t matter):”
+
+  * `Short answer`
+  * `Long answer`
+  * `Reasoning`
+  * `Assumptions`
+  * `Unknowns`
+* “If a section has nothing to say, write `None`.”
+
+**What you enforce**
+
+* Headings exist (case-insensitive match).
+* Content can be any Markdown under each heading.
+* Order is **never** required.
+
+**Extra typing rules (only if requested by spec)**
+
+* `Reasoning` is an **ordered list** (`1.`, `2.`, …) when you care about sequence.
+* `Assumptions` and `Unknowns` are **bullets** (`- ...`) when unordered.
+
+**When to use**
+
+* Most production calls where you want stable extraction.
+* Best “effort vs structure” tradeoff.
+
+---
+
+### L2 — Single-container Flex-MD (safer parsing)
+
+Goal: eliminate “extra chatter” and make extraction reliable.
+
+**What you tell the LLM**
+Everything from L1, plus:
+
+* “Return the entire answer inside one fenced Markdown block and nothing else.”
+
+Example phrasing:
+
+* “Put your full answer inside a single ` ```markdown ` fenced block. No text before or after.”
+
+**What you enforce**
+
+* Exactly one container fence, and all content is inside it.
+* Still no ordering requirement for sections.
+
+**When to use**
+
+* Tool pipelines where stray tokens break parsing.
+* You want consistent capture of the whole response.
+
+---
+
+### L3 — Fully-typed Flex-MD (max determinism, still Markdown)
+
+Goal: strongest structural guarantees, still using Markdown (not JSON output).
+
+**What you tell the LLM**
+Everything from L2, plus **stricter formatting constraints** derived from the spec:
+
+* Section presence is strict:
+
+  * all required sections must exist (and be non-empty unless allowed).
+* Section type rules are strict:
+
+  * ordered list sections must be ordered lists
+  * list sections must be bullet lists
+  * tables must be Markdown pipe tables if requested
+  * ordered tables must include a `#` column with 1..N
+
+And (important):
+
+* “Do not output JSON as the response format.”
+* “If you include JSON-like content, present it as Markdown (lists/tables), not a JSON block.”
+
+**What you enforce**
+
+* All required sections present
+* All required section type constraints met
+* All required table constraints met
+* Container constraints met
+
+**When to use**
+
+* High reliability extraction and downstream automation.
+* You can afford slightly more prompt-tax.
+
+---
+
+## Minimal instruction templates for your generator
+
+### L0 template (lowest tax)
+
+```
+Reply in Markdown.
+```
+
+### L1 template (recommended default)
+
+```
+Reply in Markdown.
+
+Include these section headings somewhere (order does not matter):
+- Short answer
+- Long answer
+- Reasoning
+- Assumptions
+- Unknowns
+
+If a section is empty, write `None`.
+```
+
+### L1 with explicit type rules (only if your spec needs them)
+
+```
+Reply in Markdown.
+
+Include these section headings somewhere (order does not matter):
+- Short answer
+- Long answer
+- Reasoning (ordered list)
+- Assumptions (list)
+- Unknowns (list)
+
+If a section is empty, write `None`.
+
+List rules:
+- Use numbered lists (1., 2., …) for ordered lists.
+- Use '-' bullets for unordered lists.
+```
+
+### L2 template (single container)
+
+````
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+
+Inside the block, include these section headings somewhere (order does not matter):
+- Short answer
+- Long answer
+- Reasoning
+- Assumptions
+- Unknowns
+
+If a section is empty, write `None`.
+````
+
+### L3 template (max strict)
+
+````
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+
+Include these section headings somewhere (order does not matter):
+- Short answer
+- Long answer
+- Reasoning (ordered list)
+- Assumptions (list)
+- Unknowns (list)
+
+If a section is empty, write `None`.
+
+Formatting rules:
+- Ordered lists use 1., 2., …
+- Unordered lists use '-' bullets.
+- If a table is used, use a Markdown pipe table with the declared columns.
+- If an ordered table is required, add a first column named '#' and number rows 1..N.
+- Do not return JSON as the response format.
+````
+
+---
+
+## How the “instructions builder” should decide what to include (tax-aware)
+
+Your generator should only include guidance that is relevant to the current spec:
+
+Include:
+
+* Section list always at L1+
+* `None` rule only if you want it (recommended at L1+ when sections are required)
+* List rules only if any required section is a list / ordered list
+* Table rules only if any required table exists (or strictness L3)
+* Container rule only at L2+
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flex-md",
-  "version": "1.1.0",
-  "description": "Parse and stringify FlexMD Frames (semi-structured Markdown) to/from JSON.",
+  "version": "3.0.0",
+  "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
   "keywords": [
@@ -10,7 +10,11 @@
     "serialization",
     "llm",
     "prompting",
-    "semi-structured"
+    "semi-structured",
+    "ofs",
+    "output-format",
+    "detection",
+    "extraction"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
@@ -24,13 +28,18 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md",
+    "SPEC.md"
   ],
   "scripts": {
     "build": "tsc && node ./scripts/cjs-bridge.mjs",
-    "test": "node ./dist/index.js"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.16"
   }
 }