flex-md 1.1.0 → 3.0.0

package/dist/strictness/types.d.ts

@@ -0,0 +1,77 @@
+export type StrictnessLevel = 0 | 1 | 2 | 3;
+export type ContainerMode = "none" | "markdown_fence" | "flexmd_fence";
+import { Enforcement } from "../types.js";
+export type { Enforcement };
+/**
+ * Semi-strict enforcement policy.
+ * Lets you be strict about some aspects (e.g. container) and lenient about others (e.g. optional sections).
+ */
+export interface SemiStrictPolicy {
+    outsideContainer?: Enforcement;
+    missingContainer?: Enforcement;
+    multipleContainers?: Enforcement;
+    missingOfs?: Enforcement;
+    missingRequiredSection?: Enforcement;
+    missingOptionalSection?: Enforcement;
+    wrongSectionKindRequired?: Enforcement;
+    wrongSectionKindOptional?: Enforcement;
+    emptySectionWithoutNoneRequired?: Enforcement;
+    emptySectionWithoutNoneOptional?: Enforcement;
+    missingRequiredTable?: Enforcement;
+    missingOptionalTable?: Enforcement;
+    orderedTableViolationsRequired?: Enforcement;
+    orderedTableViolationsOptional?: Enforcement;
+    jsonPayloadMissing?: Enforcement;
+}
+export type GuidanceMode = "auto" | "always" | "never";
+export interface StrictnessOptions {
+    level: StrictnessLevel;
+    container?: "none" | "markdown_fence" | "flexmd_fence";
+    requireSingleContainer?: boolean;
+    requireOfs?: boolean;
+    requireAllSections?: boolean;
+    enforceEmptyNone?: boolean;
+    acceptAnyHeadingLevel?: boolean;
+    duplicateSectionStrategy?: "merge" | "first";
+    requireTypedJson?: boolean;
+    jsonSchema?: unknown;
+    jsonPayloadHeading?: string;
+    /**
+     * Controls whether prompt enrichment should mention table rules.
+     * - auto: only when required/likely
+     * - always: always include table guidance if spec declares tables
+     * - never: never include table guidance
+     */
+    tablesGuidance?: GuidanceMode;
+    /**
+     * Controls whether to mention list formatting rules in the prompt.
+     * - auto: mention only if the spec includes list/ordered-list sections (and L1+)
+     * - always: mention whenever such sections exist, regardless of strictness level
+     * - never: never mention list rules
+     */
+    listsGuidance?: GuidanceMode;
+    /**
+     * Controls whether to mention the "empty sections => None" rule.
+     * - auto: mention only when spec.emptySectionValue exists and L1+
+     * - always: always mention if emptySectionValue exists
+     * - never: never mention it
+     */
+    emptyNoneGuidance?: GuidanceMode;
+    /**
+     * Controls whether to mention the container rule ("single fenced block").
+     * - auto: mention only at L2+
+     * - always: always mention (even at L1)
+     * - never: never mention (not recommended if L2+)
+     */
+    containerGuidance?: GuidanceMode;
+    /**
+     * Controls whether to mention the typed JSON rule for L3.
+     * - auto: mention only at L3 when requireTypedJson=true
+     * - always: always mention at L3
+     * - never: never mention (not recommended if you require it)
+     */
+    typedJsonGuidance?: GuidanceMode;
+    /** Optional semi-strict policy overrides. */
+    policy?: SemiStrictPolicy;
+}
+export declare function strictnessDefaults(level: StrictnessLevel): StrictnessOptions;

package/dist/strictness/types.js

@@ -0,0 +1,106 @@
+export function strictnessDefaults(level) {
+    const common = {
+        tablesGuidance: "auto",
+        listsGuidance: "auto",
+        emptyNoneGuidance: "auto",
+        containerGuidance: "auto",
+        typedJsonGuidance: "auto",
+        acceptAnyHeadingLevel: true,
+        duplicateSectionStrategy: "merge",
+    };
+    if (level === 0) {
+        return {
+            ...common,
+            level,
+            container: "none",
+            requireOfs: false,
+            requireAllSections: false,
+            policy: {
+                outsideContainer: "ignore",
+                missingContainer: "ignore",
+                multipleContainers: "ignore",
+                missingRequiredSection: "warn",
+                missingOptionalSection: "ignore",
+                wrongSectionKindRequired: "warn",
+                wrongSectionKindOptional: "ignore",
+                emptySectionWithoutNoneRequired: "warn",
+                emptySectionWithoutNoneOptional: "ignore",
+                missingRequiredTable: "warn",
+                missingOptionalTable: "ignore",
+                orderedTableViolationsRequired: "warn",
+                orderedTableViolationsOptional: "ignore",
+            }
+        };
+    }
+    if (level === 1) {
+        return {
+            ...common,
+            level,
+            container: "none",
+            requireOfs: true,
+            requireAllSections: true,
+            policy: {
+                missingRequiredSection: "error",
+                missingOptionalSection: "ignore",
+                wrongSectionKindRequired: "error",
+                wrongSectionKindOptional: "warn",
+                emptySectionWithoutNoneRequired: "error",
+                emptySectionWithoutNoneOptional: "warn",
+                missingRequiredTable: "error",
+                missingOptionalTable: "ignore",
+                orderedTableViolationsRequired: "error",
+                orderedTableViolationsOptional: "warn",
+            }
+        };
+    }
+    if (level === 2) {
+        return {
+            ...common,
+            level,
+            container: "markdown_fence",
+            requireSingleContainer: true,
+            requireOfs: true,
+            requireAllSections: true,
+            policy: {
+                outsideContainer: "error",
+                missingContainer: "error",
+                multipleContainers: "error",
+                missingRequiredSection: "error",
+                missingOptionalSection: "ignore",
+                wrongSectionKindRequired: "error",
+                wrongSectionKindOptional: "warn",
+                emptySectionWithoutNoneRequired: "error",
+                emptySectionWithoutNoneOptional: "warn",
+                missingRequiredTable: "error",
+                missingOptionalTable: "ignore",
+                orderedTableViolationsRequired: "error",
+                orderedTableViolationsOptional: "warn",
+            }
+        };
+    }
+    return {
+        ...common,
+        level: 3,
+        container: "markdown_fence",
+        requireSingleContainer: true,
+        requireOfs: true,
+        requireAllSections: true,
+        requireTypedJson: true,
+        policy: {
+            outsideContainer: "error",
+            missingContainer: "error",
+            multipleContainers: "error",
+            missingRequiredSection: "error",
+            missingOptionalSection: "ignore",
+            wrongSectionKindRequired: "error",
+            wrongSectionKindOptional: "warn",
+            emptySectionWithoutNoneRequired: "error",
+            emptySectionWithoutNoneOptional: "warn",
+            missingRequiredTable: "error",
+            missingOptionalTable: "ignore",
+            orderedTableViolationsRequired: "error",
+            orderedTableViolationsOptional: "warn",
+            jsonPayloadMissing: "error"
+        }
+    };
+}

package/dist/test-pipeline.d.ts

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

package/dist/test-pipeline.js

@@ -0,0 +1,53 @@
+import { enforceFlexMd, parseOutputFormatSpec, detectResponseKind } from "./index.js";
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(`Assertion failed: ${message}`);
+    }
+}
+console.log("🧪 Running Pipeline & JSON Detection Tests\n");
+const spec = parseOutputFormatSpec(`
+## Output format
+- Answer — prose (required)
+- Reasoning — ordered list (optional)
+`);
+// 1. Detection Kind
+console.log("--- Detection Kind ---");
+const mdResp = "## Answer\nThis is an answer.";
+const kind1 = detectResponseKind(mdResp, spec);
+console.log("FlexMD Kind:", kind1.kind);
+assert(kind1.kind === "flexmd", "Should detect flexmd");
+const issuesResp = "## Status\n- status: error\n- code: fail\n- message: fail\n\n## Issues\n- issue: x";
+const kind2 = detectResponseKind(issuesResp, spec);
+console.log("Issues Kind:", kind2.kind);
+assert(kind2.kind === "issues", "Should detect issues");
+const plainResp = "Just some text.";
+const kind3 = detectResponseKind(plainResp, spec);
+console.log("Markdown Kind:", kind3.kind);
+assert(kind3.kind === "markdown", "Should detect markdown");
+// 2. JSON fixing
+console.log("\n--- JSON Fixing ---");
+const jsonResp = "```json\n{\n  \"Answer\": \"Parsed from JSON\",\n  \"Reasoning\": [\"Step 1\", \"Step 2\"]\n}\n```";
+const resultJson = enforceFlexMd(jsonResp, spec, { level: 1 });
+console.log("JSON Fixed OK:", resultJson.ok);
+console.log("JSON Fixed Content:\n", resultJson.extracted?.sectionsByName["Answer"]?.md);
+assert(resultJson.ok === true, "Enforce should succeed with fixed JSON");
+assert(!!resultJson.extracted?.sectionsByName["Answer"]?.md.includes("Parsed from JSON"), "Should extract from fixed JSON");
+assert(resultJson.extracted?.sectionsByName["Reasoning"]?.list?.items.length === 2, "Should extract list from fixed JSON");
+// 3. Raw JSON object
+console.log("\n--- Raw JSON Object ---");
+const rawJson = "{\"Answer\": \"Raw JSON\"}";
+const resultRaw = enforceFlexMd(rawJson, spec, { level: 1 });
+console.log("Raw JSON Fixed OK:", resultRaw.ok);
+assert(resultRaw.ok === true, "Should fix raw JSON");
+// 4. Missing sections fixing
+console.log("\n--- Missing Sections ---");
+// The fixer (repairToMarkdownLevel) SHOULD add missing required sections.
+const failingResp = "## SomeOtherSection\nContent";
+const resultFixed = enforceFlexMd(failingResp, spec, { level: 1 });
+console.log("Auto-Repaired OK:", resultFixed.ok);
+console.log("Repaired Content Contains 'Answer':", resultFixed.outputText.includes("## Answer"));
+console.log("Repaired Content Contains 'None':", resultFixed.outputText.includes("None"));
+assert(resultFixed.ok === true, "Should be ok if required sections are auto-repaired");
+assert(resultFixed.outputText.includes("## Answer"), "Should have added 'Answer' heading");
+assert(resultFixed.outputText.includes("None"), "Should have filled with 'None'");
+console.log("\n✅ Pipeline Tests Passed");

package/dist/test-runner.d.ts

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

package/dist/test-runner.js

@@ -0,0 +1,331 @@
+import { 
+// Layer A
+parseFlexMd, stringifyFlexMd, validateFlexMd, 
+// Layer B
+parseOutputFormatSpec, stringifyOutputFormatSpec, enrichInstructions, validateMarkdownAgainstOfs as validateOutput, extractFromMarkdown as extractOutput, 
+// Outline
+buildOutline, renderOutline, 
+// Parsers
+parseNestedList as parseList, parsePipeTable, extractPipeTables as extractAllTables, enforceOrderedTable, 
+// Strictness
+strictnessDefaults, 
+// Layer C
+detectObjects, parseAny } from "./index.js";
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+    try {
+        fn();
+        console.log(`✅ ${name}`);
+        passed++;
+    }
+    catch (e) {
+        console.error(`❌ ${name}`);
+        console.error(e);
+        failed++;
+    }
+}
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(`Assertion failed: ${message}`);
+    }
+}
+console.log("🧪 Running FlexMD v1.1 Tests\n");
+// ============================================================================
+// Layer A Tests
+// ============================================================================
+console.log("📦 Layer A - FlexMD Frames\n");
+test("Parse basic FlexMD frame", () => {
+    const md = `[[message role=user id=m1]]
+@tags: auth, login
+Hello world
+`;
+    const doc = parseFlexMd(md);
+    assert(doc.frames.length === 1, "Should have 1 frame");
+    assert(doc.frames[0].type === "message", "Type should be message");
+    assert(doc.frames[0].role === "user", "Role should be user");
+    assert(Array.isArray(doc.frames[0].meta?.tags), "Tags should be array");
+});
+test("Stringify FlexMD frame", () => {
+    const doc = {
+        frames: [{
+                type: "message",
+                role: "user",
+                id: "m1",
+                meta: { tags: ["auth", "login"] },
+                body_md: "Hello world\n"
+            }]
+    };
+    const md = stringifyFlexMd(doc);
+    assert(md.includes("[[message"), "Should contain frame header");
+    assert(md.includes("@tags:"), "Should contain meta");
+});
+test("Parse with type inference", () => {
+    const md = `[[message]]
+@priority: 5
+@enabled: true
+@value: null
+Body text
+`;
+    const doc = parseFlexMd(md, { metaTypeMode: "infer" });
+    assert(doc.frames[0].meta?.priority === 5, "Should infer number");
+    assert(doc.frames[0].meta?.enabled === true, "Should infer boolean");
+    assert(doc.frames[0].meta?.value === null, "Should infer null");
+});
+test("Validate FlexMD", () => {
+    const valid = `[[message role=user]]
+Hello
+`;
+    const result = validateFlexMd(valid);
+    assert(result.valid === true, "Should be valid");
+});
+// ============================================================================
+// Layer B Tests
+// ============================================================================
+console.log("\n📋 Layer B - Output Format Spec\n");
+test("Parse OFS", () => {
+    const md = `## Output format (Markdown)
+Include these sections somewhere (order does not matter):
+
+- Short answer — prose
+- Reasoning — ordered list
+- Assumptions — list
+`;
+    const spec = parseOutputFormatSpec(md);
+    assert(spec !== null, "Spec should not be null");
+    assert(spec.sections.length === 3, "Should have 3 sections");
+    assert(spec.sections[0].name === "Short answer", "First section name");
+    assert(spec.sections[0].kind === "prose", "First section kind");
+    assert(spec.sections[1].kind === "ordered_list", "Second section kind");
+});
+test("Stringify OFS", () => {
+    const spec = {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: [
+            { name: "Answer", kind: "prose" }
+        ],
+        tablesOptional: true,
+        tables: [],
+        emptySectionValue: "None"
+    };
+    const md = stringifyOutputFormatSpec(spec);
+    assert(md.includes("Answer — prose"), "Should contain section");
+    assert(md.includes("None"), "Should contain empty value");
+});
+test("Enrich instructions", () => {
+    const spec = {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: [
+            { name: "Steps", kind: "ordered_list" },
+            { name: "Notes", kind: "list" }
+        ],
+        tablesOptional: true,
+        tables: [],
+        emptySectionValue: "None"
+    };
+    const instructions = enrichInstructions(spec, strictnessDefaults(1));
+    assert(instructions.includes("numbered items"), "Should mention ordered lists");
+    assert(instructions.includes("bullets"), "Should mention lists");
+    assert(instructions.includes("None"), "Should mention empty value");
+});
+test("Validate output against OFS", () => {
+    const spec = {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: [
+            { name: "Answer", kind: "prose" }
+        ],
+        tablesOptional: true,
+        tables: []
+    };
+    const md = `## Answer\nThe answer is 42.`;
+    const result = validateOutput(md, spec, strictnessDefaults(1));
+    assert(result.ok === true, "Should validate successfully");
+});
+test("Extract output from OFS", () => {
+    const spec = {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: [
+            { name: "Answer", kind: "prose" },
+            { name: "Steps", kind: "ordered_list" }
+        ],
+        tablesOptional: true,
+        tables: []
+    };
+    const md = `## Answer
+The answer is 42.
+
+## Steps
+1. First step
+2. Second step
+`;
+    const extracted = extractOutput(md, spec, strictnessDefaults(1));
+    assert(extracted.sectionsByName["Answer"].md.includes("42"), "Should extract answer");
+    assert(extracted.sectionsByName["Steps"].list?.ordered === true, "Should parse ordered list");
+    assert(extracted.sectionsByName["Steps"].list?.items.length === 2, "Should have 2 items");
+});
+// ============================================================================
+// Outline Tests
+// ============================================================================
+console.log("\n🌳 Outline & Tree Building\n");
+test("Build outline from headings", () => {
+    const md = `# Title
+Content
+
+## Section 1
+More content
+
+### Subsection 1.1
+Details
+
+## Section 2
+Other content
+`;
+    const outline = buildOutline(md);
+    assert(outline.nodes.length === 1, "Should have 1 root node");
+    assert(outline.nodes[0].title === "Title", "Root title");
+    assert(outline.nodes[0].children.length === 2, "Should have 2 children");
+    assert(outline.nodes[0].children[0].children.length === 1, "First child has 1 child");
+});
+test("Render outline back to Markdown", () => {
+    const outline = {
+        type: "md_outline",
+        nodes: [{
+                title: "Title",
+                level: 1,
+                key: "title",
+                content_md: "Content\n",
+                children: [{
+                        title: "Section",
+                        level: 2,
+                        key: "section",
+                        content_md: "More\n",
+                        children: []
+                    }]
+            }]
+    };
+    const md = renderOutline(outline);
+    assert(md.includes("# Title"), "Should have h1");
+    assert(md.includes("## Section"), "Should have h2");
+    assert(!md.includes("key"), "Should not include internal keys");
+});
+// ============================================================================
+// Parser Tests
+// ============================================================================
+console.log("\n📝 List & Table Parsers\n");
+test("Parse unordered list", () => {
+    const md = `- Item 1
+  - Nested 1.1
+- Item 2
+`;
+    const list = parseList(md);
+    assert(list !== null, "Should parse list");
+    assert(list.ordered === false, "Should be unordered");
+    assert(list.items.length === 2, "Should have 2 items");
+    assert(list.items[0].children.length === 1, "First item has 1 child");
+});
+test("Parse ordered list", () => {
+    const md = `1. First
+   1. Sub-first
+2. Second
+`;
+    const list = parseList(md);
+    assert(list !== null, "Should parse list");
+    assert(list.ordered === true, "Should be ordered");
+    assert(list.items.length === 2, "Should have 2 items");
+    assert(list.items[0].index === 1, "First item index");
+});
+test("Parse pipe table", () => {
+    const md = `| Name | Age |
+|------|-----|
+| Alice | 30 |
+| Bob | 25 |
+`;
+    const table = parsePipeTable(md);
+    assert(table !== null, "Should parse table");
+    assert(table.columns.length === 2, "Should have 2 columns");
+    assert(table.rows.length === 2, "Should have 2 rows");
+});
+test("Parse ordered table", () => {
+    const md = `| # | Task | Status |
+|---|------|--------|
+| 1 | Do it | Done |
+| 2 | Check | Pending |
+`;
+    const table = parsePipeTable(md);
+    assert(table !== null, "Should parse table");
+    const issues = enforceOrderedTable(table);
+    assert(issues.length === 0, "Should have no ordered table issues");
+    assert(table.columns[0] === "#", "First column should be #");
+});
+test("Extract all tables", () => {
+    const md = `Some text
+
+| A | B |
+|---|---|
+| 1 | 2 |
+
+More text
+
+| C | D |
+|---|---|
+| 3 | 4 |
+`;
+    const tables = extractAllTables(md);
+    assert(tables.length === 2, "Should find 2 tables");
+});
+// ============================================================================
+// Layer C Tests
+// ============================================================================
+console.log("\n🔍 Layer C - Detection & Extraction\n");
+test("Detect flexmd fence", () => {
+    const text = `Some text
+\`\`\`flexmd
+[[message]]
+Hello
+\`\`\`
+More text
+`;
+    const detected = detectObjects(text);
+    assert(detected.length > 0, "Should detect object");
+    assert(detected[0].kind === "flexmd_fence", "Should be flexmd fence");
+    assert(detected[0].confidence === 1.0, "Should have high confidence");
+});
+test("Detect JSON FlexDocument", () => {
+    const text = `\`\`\`json
+{"frames": [{"type": "message", "body_md": "Hello"}]}
+\`\`\`
+`;
+    const detected = detectObjects(text);
+    assert(detected.length > 0, "Should detect object");
+    assert(detected[0].kind === "flexdoc_json_fence", "Should be JSON FlexDoc");
+});
+test("Parse any text", () => {
+    const text = `Random text
+\`\`\`flexmd
+[[message role=user]]
+Hello
+\`\`\`
+More text
+`;
+    const result = parseAny(text);
+    assert(result.flexDocs.length === 1, "Should extract 1 FlexDoc");
+    assert(result.flexDocs[0].frames.length === 1, "Should have 1 frame");
+});
+// ============================================================================
+// Summary
+// ============================================================================
+console.log("\n" + "=".repeat(50));
+console.log(`✅ Passed: ${passed}`);
+console.log(`❌ Failed: ${failed}`);
+console.log("=" + "=".repeat(50));
+if (failed > 0) {
+    throw new Error("Tests failed");
+}

package/dist/test-strictness.d.ts

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