flex-md 4.7.2 → 4.7.4

package/dist-cjs/validate/compliance.cjs

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCompliance = checkCompliance;
+exports.hasFlexMdContract = hasFlexMdContract;
+const parser_js_1 = require("../ofs/parser.cjs");
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * Returns detailed results including what's missing or wrong.
+ * Now also checks for Input Format Spec if present.
+ */
+async function checkCompliance(instructions, complianceLevel) {
+    const issues = [];
+    const suggestions = [];
+    const lower = instructions.toLowerCase();
+    // Extract both input and output format specs
+    const formatSpecs = (0, parser_js_1.parseFormatSpecs)(instructions);
+    const hasInputFormat = !!formatSpecs.input;
+    const hasOutputFormat = !!formatSpecs.output;
+    const hasMarkdownMention = lower.includes("markdown");
+    const hasSectionMention = lower.includes("section") || lower.includes("heading");
+    const hasContainerMention = (lower.includes("fenced block") || lower.includes("```")) && (lower.includes("inside") || lower.includes("wrapped"));
+    const hasNoneRule = lower.includes("none") && lower.includes("empty");
+    const hasListRules = lower.includes("list rules") || (lower.includes("ordered list") && lower.includes("unordered list"));
+    const hasTableRules = lower.includes("table") && lower.includes("pipe");
+    const levelNum = parseInt(complianceLevel.slice(1));
+    // L0 requirements
+    if (levelNum >= 0) {
+        if (!hasMarkdownMention) {
+            issues.push({
+                type: "other",
+                description: "Instructions do not mention 'Markdown'.",
+                severity: "error",
+                suggestion: "Add 'Reply in Markdown.' to your instructions."
+            });
+        }
+    }
+    // L1 requirements
+    if (levelNum >= 1) {
+        if (!hasSectionMention) {
+            issues.push({
+                type: "missing-section",
+                description: "Instructions do not specify required sections or headings.",
+                severity: "error",
+                suggestion: "Include a list of required section headings."
+            });
+        }
+    }
+    // L2 requirements
+    if (levelNum >= 2) {
+        if (!hasContainerMention) {
+            issues.push({
+                type: "missing-container",
+                description: "Instructions do not require a fenced container block (L2+ requirement).",
+                severity: "error",
+                suggestion: "Add 'Return your entire answer inside a single ```markdown fenced block and nothing else.' to your instructions."
+            });
+        }
+    }
+    // L3 requirements
+    if (levelNum >= 3) {
+        if (!hasNoneRule) {
+            issues.push({
+                type: "other",
+                description: "Instructions are missing the 'None' rule for empty sections (L3 requirement).",
+                severity: "warning",
+                suggestion: "Add 'If a section is empty, write `None`.' to your instructions."
+            });
+        }
+        if (!hasListRules) {
+            issues.push({
+                type: "invalid-format",
+                description: "Instructions are missing specific list formatting rules (L3 requirement).",
+                severity: "warning",
+                suggestion: "Add bullet and numbered list formatting instructions."
+            });
+        }
+    }
+    const meetsCompliance = !issues.some(i => i.severity === "error");
+    if (!meetsCompliance) {
+        suggestions.push(...issues.map(i => i.suggestion).filter((s) => !!s));
+    }
+    return {
+        meetsCompliance,
+        complianceLevel,
+        issues,
+        suggestions,
+        metadata: {
+            hasContainer: hasContainerMention,
+            hasRequiredSections: hasSectionMention,
+            containerType: hasContainerMention ? "fenced-block" : "none",
+            hasInputFormat,
+            hasOutputFormat
+        }
+    };
+}
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * @deprecated Use checkCompliance for detailed results.
+ */
+async function hasFlexMdContract(instructions, complianceLevel) {
+    const result = await checkCompliance(instructions, complianceLevel);
+    return result.meetsCompliance;
+}

package/dist-cjs/validate/connection.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkConnection = checkConnection;
+const outline_js_1 = require("../md/outline.cjs");
+const parse_js_1 = require("../md/parse.cjs");
+/**
+ * Checks if a specific key (section) is "connected" in the given markdown.
+ */
+function checkConnection(md, key) {
+    const outline = (0, outline_js_1.buildOutline)(md);
+    const normKey = (0, parse_js_1.normalizeName)(key);
+    const path = [];
+    // Breadth-first search for the key
+    const queue = outline.nodes.map(n => ({ node: n, currentPath: [n.title] }));
+    const alternatives = [];
+    while (queue.length > 0) {
+        const { node, currentPath } = queue.shift();
+        if (node.key === normKey) {
+            return {
+                connected: true,
+                key,
+                normalizedKey: normKey,
+                path: currentPath
+            };
+        }
+        // Collect alternatives (any heading that exists)
+        alternatives.push(node.title);
+        for (const child of node.children) {
+            queue.push({ node: child, currentPath: [...currentPath, child.title] });
+        }
+    }
+    // Not found, look for fuzzy matches or common issues
+    const suggestions = [];
+    if (alternatives.length === 0) {
+        suggestions.push("The document appears to have no headings.");
+    }
+    else {
+        suggestions.push(`Available sections: ${alternatives.join(", ")}`);
+    }
+    return {
+        connected: false,
+        key,
+        normalizedKey: normKey,
+        alternativeMatches: alternatives,
+        suggestion: suggestions.join(" ")
+    };
+}

package/dist-cjs/validate/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/validate/validate.cjs

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMarkdownAgainstOfs = validateMarkdownAgainstOfs;
+const parse_js_1 = require("../md/parse.cjs");
+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 = (0, parse_js_1.extractFencedBlocks)(input);
+    if (fences.length === 1) {
+        const f = fences[0];
+        return { working: f.content, container: { fence: f } };
+    }
+    return { working: input, container: null };
+}
+function validateMarkdownAgainstOfs(input, spec, level, policyOverride) {
+    const policy = { ...defaultPolicy(level), ...(policyOverride ?? {}) };
+    const issues = [];
+    const fencesAll = (0, parse_js_1.extractFencedBlocks)(input);
+    if (level === 0) {
+        const env = (0, parse_js_1.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 = (0, parse_js_1.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 = (0, parse_js_1.parseHeadingsAndSections)(working);
+    const specByNorm = new Map();
+    for (const s of spec.sections)
+        specByNorm.set((0, parse_js_1.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 = (0, parse_js_1.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 = (0, parse_js_1.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 => (0, parse_js_1.normalizeName)(b) === (0, parse_js_1.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 = (0, parse_js_1.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 ((0, parse_js_1.normalizeName)(b) === (0, parse_js_1.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 => (0, parse_js_1.normalizeName)(c));
+                    if (cols.length) {
+                        const headerNorm = table.header.map(c => (0, parse_js_1.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 = (0, parse_js_1.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,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Compute detectedKind more robustly: if we found more than zero sections, it's at least sectioned
+    let detectedKind = "markdown";
+    if (level >= 2) {
+        detectedKind = fencesAll.length > 0 ? "fenced" : (parsed.length > 0 ? "sectioned" : "markdown");
+    }
+    else {
+        detectedKind = parsed.length > 0 ? "sectioned" : "markdown";
+    }
+    const ok = !issues.some(i => i.severity === "error");
+    return {
+        ok,
+        level,
+        issues,
+        stats: {
+            detectedKind,
+            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/consumption.md

@@ -4,7 +4,7 @@ This document is for library/tool authors (gateways, SDK adapters, orchestrators
 
 ## Node support baseline
 
-- `flex-md` supports Node LTS in the range `>=18 <22`.
+- `flex-md` supports Node LTS in the range `>=18`.
 - Release validation should run `npm run build` then `npm run test:smoke`.
 
 ## Export map behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -19,11 +19,11 @@
   "ts-node": {
     "esm": true
   },
-  "type": "commonjs",
+  "type": "module",
   "engines": {
-    "node": ">=18 <22"
+    "node": ">=18"
   },
-  "main": "./dist/index.cjs",
+  "main": "./dist-cjs/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
@@ -33,26 +33,32 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "require": "./dist-cjs/index.cjs"
     }
   },
   "files": [
     "dist",
+    "dist-cjs",
     "docs",
     "athenices-ai-gateway.md",
     "README.md",
     "SPEC.md"
   ],
   "scripts": {
-    "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/cjs-bridge.mjs",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/emit-cjs-extensions.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:smoke": "node test/smoke-require.cjs && node test/smoke-import.mjs && node test/smoke-package-resolution.cjs",
     "deps:latest": "npx npm-check-updates -u && npm install"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.16"
+  },
   "dependencies": {
-    "micro-logs": "^1.0.0",
+    "micro-logs": "^1.0.5",
     "nx-helpers": "^1.5.0",
     "nx-json-parser": "^1.3.0",
     "nx-md-parser": "^2.2.1"