flex-md 3.0.0 → 3.2.0

package/README.md

@@ -9,8 +9,8 @@ Version 3.0 introduces the **Detect-Repair-Enforce** pipeline, ensuring LLM resp
 - **Standard Markdown**: No proprietary tags. Pure headings, lists, and tables.
 - **Strictness Levels (L0–L3)**: From loose guidance to rigid structural enforcement.
 - **Deterministic Repair**: Auto-fixes misformatted LLM output (merged fences, missing headings, format conversion).
+- **Instructions Output Format Guidance**: Generate formal "Instructions Blocks" for LLM prompts directly from spec objects.
 - **Issues Envelope**: A structured failure format for when repairs fail, allowing safe fallbacks.
-- **Tax-Aware Prompts**: Generates minimal, relevant instructions to save tokens.
 
 ## Installation
 
@@ -61,6 +61,35 @@ if (result.ok) {
 }
 ```
 
+### 4. Dynamic Instructions Output Format Blocks
+
+You can also define your spec as a plain JavaScript object and generate the formal "Instructions Block" for your LLM prompts.
+
+```typescript
+import { stringifyOutputFormatSpec } from 'flex-md';
+
+const spec = {
+  description: "Standard report format for technical analysis.",
+  sections: [
+    {
+      name: "Summary",
+      kind: "text",
+      required: true,
+      description: "A brief summary of the topic."
+    },
+    {
+      name: "Key Points",
+      kind: "list",
+      required: false,
+      instruction: "Include at least 3 bullet points."
+    }
+  ]
+};
+
+const instructionsBlock = stringifyOutputFormatSpec(spec);
+// Output will include the ## Output format (Markdown) header, descriptions, and instructions.
+```
+
 ## Strictness Levels
 
 | Level | Goal | Guidance | Enforcement |

package/dist/__tests__/diagnostics.test.d.ts

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

package/dist/__tests__/diagnostics.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { checkCompliance, hasFlexMdContract, enrichInstructionsWithFlexMd, validateFormat } from "../index.js";
+describe("Diagnostics", () => {
+    describe("checkCompliance", () => {
+        it("should return meetsCompliance: true for L0 if Markdown is mentioned", async () => {
+            const res = await checkCompliance("Reply in Markdown.", "L0");
+            expect(res.meetsCompliance).toBe(true);
+            expect(res.issues).toHaveLength(0);
+        });
+        it("should return issues for L2 if container is missing", async () => {
+            const res = await checkCompliance("Reply in Markdown. Include headings.", "L2");
+            expect(res.meetsCompliance).toBe(false);
+            expect(res.issues.some(i => i.type === "missing-container")).toBe(true);
+        });
+        it("should return false for hasFlexMdContract if requirements not met", async () => {
+            const ok = await hasFlexMdContract("Hello", "L0");
+            expect(ok).toBe(false);
+        });
+    });
+    describe("enrichInstructionsWithFlexMd", () => {
+        it("should append guidance to existing instructions", async () => {
+            const res = await enrichInstructionsWithFlexMd("Do a good job.", "L0");
+            expect(res.enriched).toContain("Do a good job.");
+            expect(res.enriched).toContain("Reply in Markdown.");
+            expect(res.changes).toHaveLength(1);
+            expect(res.metadata?.guidanceAdded).toBe(true);
+        });
+        it("should track container addition for L2", async () => {
+            const res = await enrichInstructionsWithFlexMd("Do a good job.", "L2");
+            expect(res.changes.some(c => c.type === "added-container")).toBe(true);
+            expect(res.metadata?.containerAdded).toBe(true);
+        });
+    });
+    describe("validateFormat", () => {
+        it("should validate a correct flex-md OFS", async () => {
+            const ofs = `## Output format\n- Summary — prose\n- Actions — list`;
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(true);
+            expect(res.metadata?.sectionCount).toBe(2);
+        });
+        it("should return errors for missing heading", async () => {
+            const ofs = `- Summary — prose`;
+            const res = await validateFormat(ofs);
+            expect(res.valid).toBe(false);
+            expect(res.issues.some(i => i.type === "missing-heading")).toBe(true);
+        });
+        it("should validate JSON schema", async () => {
+            const schema = `{"type": "object"}`;
+            const res = await validateFormat(schema, "json-schema");
+            expect(res.valid).toBe(true);
+        });
+        it("should fail on invalid JSON schema", async () => {
+            const schema = `{"type": "object"`;
+            const res = await validateFormat(schema, "json-schema");
+            expect(res.valid).toBe(false);
+            expect(res.issues[0].type).toBe("syntax-error");
+        });
+    });
+});

package/dist/__tests__/ofs.test.d.ts

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

package/dist/__tests__/ofs.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { stringifyOutputFormatSpec } from "../ofs/stringify.js";
+import { buildMarkdownGuidance } from "../ofs/enricher.js";
+describe("Instructions Output Format Block Generation", () => {
+    const spec = {
+        description: "Standard report format for technical analysis.",
+        sections: [
+            {
+                name: "Summary",
+                kind: "text",
+                required: true,
+                description: "A brief summary of the topic.",
+                instruction: "Keep it under 3 sentences."
+            },
+            {
+                name: "Key Points",
+                kind: "list",
+                required: false,
+                description: "Important takeaways."
+            }
+        ],
+        emptySectionValue: "N/A"
+    };
+    it("should stringify an OFS object correctly", () => {
+        const md = stringifyOutputFormatSpec(spec);
+        expect(md).toContain("## Output format (Markdown)");
+        expect(md).toContain("Standard report format for technical analysis.");
+        expect(md).toContain("- Summary — text (required)");
+        expect(md).toContain("Description: A brief summary of the topic.");
+        expect(md).toContain("Instruction: Keep it under 3 sentences.");
+        expect(md).toContain("- Key Points — list (optional)");
+        expect(md).toContain("Description: Important takeaways.");
+        expect(md).toContain("If a section is empty, write `N/A`.");
+    });
+    it("should build markdown guidance (L1) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 1 });
+        expect(guidance).toContain("Include these section headings somewhere");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("Description: A brief summary of the topic.");
+        expect(guidance).toContain("Instruction: Keep it under 3 sentences.");
+        expect(guidance).toContain("- Key Points");
+        expect(guidance).toContain("Description: Important takeaways.");
+    });
+    it("should build markdown guidance (L3) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 3 });
+        expect(guidance).toContain("Return your entire answer inside a single ```markdown fenced block");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("- Key Points (list)");
+        expect(guidance).toContain("Do not return JSON");
+    });
+});

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 export * from "./types.js";
 export * from "./strictness/types.js";
 export * from "./md/parse.js";
-export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";
 export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
-export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+export { buildMarkdownGuidance, enrichInstructions, enrichInstructionsWithFlexMd } from "./ofs/enricher.js";
 export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { checkCompliance, hasFlexMdContract } from "./validate/compliance.js";
 export { extractFromMarkdown } from "./extract/extract.js";
 export { processResponseMarkdown } from "./strictness/processor.js";
 export { parseIssuesEnvelope, buildIssuesEnvelope, buildIssuesEnvelopeAuto } from "./ofs/issuesEnvelope.js";

package/dist/index.js

@@ -4,11 +4,12 @@ export * from "./strictness/types.js";
 // Shared MD Parsing
 export * from "./md/parse.js";
 // Output Format Spec (OFS)
-export { parseOutputFormatSpec } from "./ofs/parser.js";
+export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";
 export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
-export { buildMarkdownGuidance, enrichInstructions } from "./ofs/enricher.js";
+export { buildMarkdownGuidance, enrichInstructions, enrichInstructionsWithFlexMd } from "./ofs/enricher.js";
 // Validation & Extraction
 export { validateMarkdownAgainstOfs } from "./validate/validate.js";
+export { checkCompliance, hasFlexMdContract } from "./validate/compliance.js";
 export { extractFromMarkdown } from "./extract/extract.js";
 // Processor & Fallback
 export { processResponseMarkdown } from "./strictness/processor.js";

package/dist/ofs/enricher.d.ts

@@ -1,4 +1,4 @@
-import { OutputFormatSpec } from "../types.js";
+import { OutputFormatSpec, EnhancementResult } from "../types.js";
 import { StrictnessOptions } from "../strictness/types.js";
 /**
  * Generates Markdown guidance instructions for the LLM based on the OFS and contract level.
@@ -14,3 +14,8 @@ export declare function buildMarkdownGuidance(spec: OutputFormatSpec, strict: St
  * @deprecated Use buildMarkdownGuidance
  */
 export declare function enrichInstructions(spec: OutputFormatSpec, strict: StrictnessOptions): string;
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+export declare function enrichInstructionsWithFlexMd(instructions: string, strictnessLevel: "L0" | "L1" | "L2" | "L3", spec?: OutputFormatSpec): Promise<EnhancementResult>;

package/dist/ofs/enricher.js

@@ -31,6 +31,14 @@ export function buildMarkdownGuidance(spec, strict, opts) {
                 suffix = " (ordered list)";
         }
         lines.push(`- ${s.name}${suffix}`);
+        if (level >= 1) {
+            if (s.description) {
+                lines.push(`  Description: ${s.description}`);
+            }
+            if (s.instruction) {
+                lines.push(`  Instruction: ${s.instruction}`);
+            }
+        }
     }
     lines.push("");
     // None Rule
@@ -75,3 +83,64 @@ export function buildMarkdownGuidance(spec, strict, opts) {
 export function enrichInstructions(spec, strict) {
     return buildMarkdownGuidance(spec, strict);
 }
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+export async function enrichInstructionsWithFlexMd(instructions, strictnessLevel, spec // Optional spec, if provided will include section guidance
+) {
+    const originalLength = instructions.length;
+    const level = parseInt(strictnessLevel.slice(1));
+    // Default spec if none provided (minimal)
+    const effectiveSpec = spec ?? { sections: [] };
+    const guidance = buildMarkdownGuidance(effectiveSpec, { level });
+    // Check if guidance is already present (simple check)
+    if (instructions.includes(guidance)) {
+        return {
+            enriched: instructions,
+            changes: [],
+            originalLength,
+            enhancedLength: originalLength,
+            metadata: {
+                sectionsAdded: 0,
+                containerAdded: false,
+                guidanceAdded: false
+            }
+        };
+    }
+    const separator = instructions.trim().length > 0 ? "\n\n" : "";
+    const enriched = instructions.trim() + separator + guidance;
+    const enhancedLength = enriched.length;
+    const changes = [
+        {
+            type: "added-guidance",
+            description: `Added Flex-MD ${strictnessLevel} compliance guidance.`,
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            },
+            content: guidance
+        }
+    ];
+    if (level >= 2) {
+        changes.push({
+            type: "added-container",
+            description: "Added requirement for a fenced container block.",
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            }
+        });
+    }
+    return {
+        enriched,
+        changes,
+        originalLength,
+        enhancedLength,
+        metadata: {
+            sectionsAdded: effectiveSpec.sections.length,
+            containerAdded: level >= 2,
+            guidanceAdded: true
+        }
+    };
+}

package/dist/ofs/parser.d.ts

@@ -1,4 +1,9 @@
-import type { OutputFormatSpec } from "../types.js";
+import type { OutputFormatSpec, FormatValidationResult } from "../types.js";
+/**
+ * Validate a format specification.
+ * Returns detailed validation results.
+ */
+export declare function validateFormat(formatSpec: string, formatType?: "flex-md" | "json-schema"): Promise<FormatValidationResult>;
 /**
  * Parse an Output Format Spec block from Markdown.
  */

package/dist/ofs/parser.js

@@ -1,3 +1,73 @@
+/**
+ * Validate a format specification.
+ * Returns detailed validation results.
+ */
+export async function validateFormat(formatSpec, formatType = "flex-md") {
+    const issues = [];
+    const suggestions = [];
+    if (formatType === "json-schema") {
+        try {
+            JSON.parse(formatSpec);
+            return {
+                valid: true,
+                formatType: "json-schema",
+                issues: [],
+                suggestions: [],
+                metadata: {
+                    structureType: "json"
+                }
+            };
+        }
+        catch (e) {
+            return {
+                valid: false,
+                formatType: "json-schema",
+                issues: [{
+                        type: "syntax-error",
+                        description: `Invalid JSON: ${e.message}`,
+                        severity: "error"
+                    }],
+                suggestions: ["Ensure the format specification is valid JSON."],
+                metadata: {
+                    structureType: "json"
+                }
+            };
+        }
+    }
+    // flex-md validation
+    const spec = parseOutputFormatSpec(formatSpec);
+    if (!formatSpec.toLowerCase().includes("output format")) {
+        issues.push({
+            type: "missing-heading",
+            description: "Missing '## Output format' heading.",
+            severity: "error",
+            suggestion: "Add '## Output format' to start the specification block."
+        });
+    }
+    if (!spec || spec.sections.length === 0) {
+        issues.push({
+            type: "missing-section",
+            description: "No sections detected in the specification.",
+            severity: "error",
+            suggestion: "Add at least one section using the '- Name — Kind' format."
+        });
+    }
+    const valid = !issues.some(i => i.severity === "error");
+    if (!valid) {
+        suggestions.push(...issues.map(i => i.suggestion).filter((s) => !!s));
+    }
+    return {
+        valid,
+        formatType: "flex-md",
+        issues,
+        suggestions,
+        metadata: {
+            sectionCount: spec?.sections.length ?? 0,
+            hasContainer: formatSpec.includes("```"),
+            structureType: "markdown"
+        }
+    };
+}
 export function parseOutputFormatSpec(md, opts = {}) {
     const headingRx = opts.headingRegex ?? /^##\s*Output format\b/i;
     const lines = md.split("\n");

package/dist/ofs/stringify.d.ts

@@ -1,5 +1,5 @@
 import type { OutputFormatSpec } from "../types.js";
 /**
- * Convert an OutputFormatSpec to canonical Markdown format.
+ * Convert an OutputFormatSpec to a formal "Instructions Output Format Block".
  */
 export declare function stringifyOutputFormatSpec(spec: OutputFormatSpec): string;

package/dist/ofs/stringify.js

@@ -1,15 +1,25 @@
 /**
- * Convert an OutputFormatSpec to canonical Markdown format.
+ * Convert an OutputFormatSpec to a formal "Instructions Output Format Block".
  */
 export function stringifyOutputFormatSpec(spec) {
     const lines = [];
     lines.push(`## Output format (Markdown)`);
+    if (spec.description) {
+        lines.push(spec.description);
+        lines.push("");
+    }
     lines.push(`Include these sections somewhere (order does not matter):`);
     lines.push("");
     for (const s of spec.sections) {
         const k = s.kind === "ordered_list" ? "ordered list" : (s.kind || "text");
         const required = s.required === true ? " (required)" : (s.required === false ? " (optional)" : "");
         lines.push(`- ${s.name} — ${k}${required}`);
+        if (s.description) {
+            lines.push(`  Description: ${s.description}`);
+        }
+        if (s.instruction) {
+            lines.push(`  Instruction: ${s.instruction}`);
+        }
     }
     const tables = spec.tables || [];
     if (tables.length) {

package/dist/types.d.ts

@@ -86,6 +86,8 @@ export interface OutputSectionSpec {
     kind?: SectionKind;
     required?: boolean;
     columns?: string[];
+    description?: string;
+    instruction?: string;
 }
 /**
  * @deprecated Use OutputSectionSpec
@@ -101,6 +103,7 @@ export interface OfsTable {
     required?: boolean;
 }
 export interface OutputFormatSpec {
+    description?: string;
     sections: OutputSectionSpec[];
     emptySectionValue?: string;
     descriptorType?: "output_format_spec";
@@ -174,3 +177,69 @@ export interface IssuesEnvelope {
         bullets: string[];
     }>;
 }
+export interface ComplianceIssue {
+    type: "missing-section" | "missing-container" | "invalid-format" | "missing-heading" | "other";
+    description: string;
+    severity: "error" | "warning";
+    location?: {
+        start: number;
+        end: number;
+        line?: number;
+        column?: number;
+    };
+    suggestion?: string;
+}
+export interface ComplianceCheckResult {
+    meetsCompliance: boolean;
+    complianceLevel: "L0" | "L1" | "L2" | "L3";
+    issues: ComplianceIssue[];
+    suggestions: string[];
+    metadata?: {
+        hasContainer?: boolean;
+        hasRequiredSections?: boolean;
+        sectionCount?: number;
+        containerType?: "fenced-block" | "none";
+    };
+}
+export interface EnhancementChange {
+    type: "added-section" | "added-container" | "modified-section" | "added-guidance" | "other";
+    description: string;
+    location: {
+        start: number;
+        end: number;
+    };
+    content?: string;
+}
+export interface EnhancementResult {
+    enriched: string;
+    changes: EnhancementChange[];
+    originalLength: number;
+    enhancedLength: number;
+    metadata?: {
+        sectionsAdded?: number;
+        containerAdded?: boolean;
+        guidanceAdded?: boolean;
+    };
+}
+export interface FormatValidationIssue {
+    type: "syntax-error" | "missing-section" | "invalid-structure" | "invalid-markdown" | "missing-heading" | "other";
+    description: string;
+    severity: "error" | "warning";
+    location?: {
+        start: number;
+        end: number;
+        line?: number;
+    };
+    suggestion?: string;
+}
+export interface FormatValidationResult {
+    valid: boolean;
+    formatType: "flex-md" | "json-schema" | "other" | "unknown";
+    issues: FormatValidationIssue[];
+    suggestions: string[];
+    metadata?: {
+        sectionCount?: number;
+        hasContainer?: boolean;
+        structureType?: string;
+    };
+}

package/dist/validate/compliance.d.ts

@@ -0,0 +1,11 @@
+import { ComplianceCheckResult } from "../types.js";
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * Returns detailed results including what's missing or wrong.
+ */
+export declare function checkCompliance(instructions: string, complianceLevel: "L0" | "L1" | "L2" | "L3"): Promise<ComplianceCheckResult>;
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * @deprecated Use checkCompliance for detailed results.
+ */
+export declare function hasFlexMdContract(instructions: string, complianceLevel: "L0" | "L1" | "L2" | "L3"): Promise<boolean>;

package/dist/validate/compliance.js

@@ -0,0 +1,91 @@
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * Returns detailed results including what's missing or wrong.
+ */
+export async function checkCompliance(instructions, complianceLevel) {
+    const issues = [];
+    const suggestions = [];
+    const lower = instructions.toLowerCase();
+    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"
+        }
+    };
+}
+/**
+ * Check if instructions meet the required flex-md compliance level.
+ * @deprecated Use checkCompliance for detailed results.
+ */
+export async function hasFlexMdContract(instructions, complianceLevel) {
+    const result = await checkCompliance(instructions, complianceLevel);
+    return result.meetsCompliance;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",