flex-md 1.1.0 → 3.0.0

package/dist/test-strictness.js

@@ -0,0 +1,213 @@
+import { parseOutputFormatSpec, processResponseMarkdown, strictnessDefaults } from "../src/index.js";
+const specText = `
+## Output format (Markdown)
+Include these sections somewhere (order does not matter):
+
+- Short answer — prose
+- Long answer — prose
+- Reasoning — ordered list
+- Assumptions — list
+- Unknowns — list
+
+tables:
+- (property, value — table)
+
+empty sections:
+- If a section is empty, write \`None\`.
+`;
+const spec = parseOutputFormatSpec(specText);
+// --- L0 Test ---
+console.log("--- Level 0 Test ---");
+const l0Response = `
+I thought about it.
+## Short answer
+Yes, it works.
+
+## Unknowns
+- None so far.
+`;
+const l0Result = processResponseMarkdown(l0Response, spec, strictnessDefaults(0));
+console.log("L0 OK:", l0Result.ok);
+console.log("L0 Issues:", l0Result.issues);
+// --- L1 Test ---
+console.log("\n--- Level 1 Test ---");
+const l1Response = `
+## Short answer
+Yes.
+
+## Long answer
+Full details.
+
+## Reasoning
+1. Step one.
+2. Step two.
+
+## Assumptions
+- Assumption A.
+
+## Unknowns
+None
+`;
+const l1Result = processResponseMarkdown(l1Response, spec, strictnessDefaults(1));
+console.log("L1 OK:", l1Result.ok);
+console.log("L1 Issues:", l1Result.issues);
+// --- L2 Test ---
+console.log("\n--- Level 2 Test ---");
+const l2Response = `
+Some chatter before.
+\`\`\`markdown
+## Short answer
+Yes.
+## Long answer
+None
+## Reasoning
+1. A
+## Assumptions
+None
+## Unknowns
+None
+\`\`\`
+Some chatter after.
+`;
+const l2Result = processResponseMarkdown(l2Response, spec, strictnessDefaults(2));
+console.log("L2 OK (should be false if chatter exists):", l2Result.ok);
+console.log("L2 Issues (should include 'content_outside_container'):", l2Result.issues);
+const l2ResponseClean = `\`\`\`markdown
+## Short answer
+Yes.
+## Long answer
+None
+## Reasoning
+1. A
+## Assumptions
+None
+## Unknowns
+None
+\`\`\``;
+const l2ResultClean = processResponseMarkdown(l2ResponseClean, spec, strictnessDefaults(2));
+console.log("L2 Clean OK:", l2ResultClean.ok);
+// --- L3 Test ---
+console.log("\n--- Level 3 Test ---");
+const l3Response = `\`\`\`markdown
+## Short answer
+Data processed.
+## Long answer
+None
+## Reasoning
+1. Step
+## Assumptions
+None
+## Unknowns
+None
+
+\`\`\`json
+{ "status": "success", "val": 42 }
+\`\`\`
+\`\`\``;
+// The regex in processor.ts is: /```json\s*\n([\s\S]*?)\n```/i
+// Let's see why it failed. Ah, the innerMarkdown was extracted but maybe the nested blocks were messed up.
+// Actually, l3Result returned issues: [ 'content_outside_container', 'json_payload_missing' ]
+// content_outside_container is due to the trailing \`\`\` outside if the first one was matched greedily? 
+// No, regex is non-greedy in container.ts: /\`\`\`" + fenceLang + "\\s*\\n([\\s\\S]*?)\\n\`\`\`/i
+// Wait, the container extractor in container.ts uses: /\`\`\`" + fenceLang + "\\s*\\n([\\s\\S]*?)\\n\`\`\`/i
+// In my L3 test:
+// \`\`\`markdown
+// ...
+// \`\`\`json
+// ...
+// \`\`\`
+// \`\`\`
+// The second to last \`\`\` matches the end of the markdown block. The last \`\`\` is "outside".
+const l3ResponseFixed = `\`\`\`markdown
+## Short answer
+Data processed.
+## Long answer
+None
+## Reasoning
+1. Step
+## Assumptions
+None
+## Unknowns
+None
+
+\`\`\`json
+{ "status": "success", "val": 42 }
+\`\`\`
+\`\`\``;
+// In this one there are two closing fences.
+const l3ResponseSimple = `\`\`\`markdown
+## Short answer
+Data processed.
+## Long answer
+None
+## Reasoning
+1. Step
+## Assumptions
+None
+## Unknowns
+None
+
+\`\`\`json
+{ "status": "success", "val": 42 }
+\`\`\`
+\`\`\``;
+// Let's try again with a simpler L3 mock
+const l3ResponseSuccess = `\`\`\`markdown
+## Short answer
+Done.
+## Long answer
+None
+## Reasoning
+1. A
+## Assumptions
+None
+## Unknowns
+None
+
+\`\`\`json
+{"ok": true}
+\`\`\`
+\`\`\``;
+const lResult3 = processResponseMarkdown(l3ResponseSuccess, spec, strictnessDefaults(3));
+console.log("L3 Success OK:", lResult3.ok);
+console.log("L3 Issues:", lResult3.issues);
+// --- Semi-Strict Test ---
+console.log("\n--- Semi-Strict Test ---");
+const semiStrictSpecText = `
+## Output format
+- Answer — prose (required)
+- Extra — list (optional)
+`;
+const semiStrictSpec = parseOutputFormatSpec(semiStrictSpecText);
+const semiStrictResponse = `
+## Answer
+This is the answer.
+`;
+// Level 1 defaults to requireAllSections: true. 
+// But "Extra" is marked (optional).
+const semiStrictResult = processResponseMarkdown(semiStrictResponse, semiStrictSpec, { level: 1 });
+console.log("Semi-Strict Missing Optional OK:", semiStrictResult.ok); // Should be true
+console.log("Semi-Strict Issues:", semiStrictResult.issues);
+const semiStrictResponseError = `
+## Extra
+- Something
+`;
+const semiStrictResultError = processResponseMarkdown(semiStrictResponseError, semiStrictSpec, { level: 1 });
+console.log("Semi-Strict Missing Required OK:", semiStrictResultError.ok); // Should be false
+console.log("Semi-Strict Issues (should have missing_section:Answer):", semiStrictResultError.issues.map((i) => i.code));
+// --- Mode B (Issues Envelope) Test ---
+console.log("\n--- Mode B Test ---");
+const modeBResponse = `
+## Status
+- status: error
+- code: missing_input
+- message: The user forgot the org_id.
+
+## Issues
+- issue: missing_org_id
+  hint: please provide org_id
+`;
+const modeBResult = processResponseMarkdown(modeBResponse, semiStrictSpec, { level: 1 });
+console.log("Mode B Detected:", !!modeBResult.issuesEnvelope);
+console.log("Mode B Status Code:", modeBResult.issuesEnvelope?.status.code);
+console.log("Mode B OK (should be false for error status):", modeBResult.ok);

package/dist/types.d.ts

@@ -1,12 +1,8 @@
 export type FlexMetaValue = string | string[] | number | boolean | null;
 export interface FlexPayload {
-    /** Language from the fenced block, e.g. "json", "yaml", "text" */
     lang?: string;
-    /** Parsed value for json fences; otherwise a string raw value */
     value: unknown;
-    /** Raw text inside the fence (no surrounding ``` lines) */
     raw: string;
-    /** If lang=json but parsing failed */
     parseError?: string;
 }
 export interface FlexFrame {
@@ -14,37 +10,23 @@ export interface FlexFrame {
     role?: string;
     id?: string;
     ts?: string;
-    /** Metadata from @key: lines */
     meta?: Record<string, FlexMetaValue>;
-    /** Body markdown between header/meta and next frame header */
     body_md?: string;
-    /** Payloads keyed by @payload:name: X */
     payloads?: Record<string, FlexPayload>;
 }
 export interface FlexDocument {
+    title?: string;
+    meta?: Record<string, FlexMetaValue>;
     frames: FlexFrame[];
 }
 export interface ParseOptions {
-    /**
-     * Which metadata keys should be split by commas into string[]
-     * Default: ["tags", "refs"]
-     */
     arrayMetaKeys?: string[];
+    metaTypeMode?: "strings" | "infer" | "schema";
+    metaSchema?: Record<string, "string" | "number" | "boolean" | "null">;
 }
 export interface StringifyOptions {
-    /**
-     * If true, omit empty sections when converting JSON -> FlexMD.
-     * Default: true
-     */
     skipEmpty?: boolean;
-    /**
-     * Which meta keys should be rendered as comma-separated lists if arrays.
-     * Default: ["tags", "refs"]
-     */
     arrayMetaKeys?: string[];
-    /**
-     * Preferred fence marker. Default: "```"
-     */
     fence?: "```" | "~~~";
 }
 export interface FlexValidationError {
@@ -56,3 +38,139 @@ export interface FlexValidationResult {
     valid: boolean;
     errors: FlexValidationError[];
 }
+export type ResponseKind = "flexmd" | "issues" | "markdown";
+export type Enforcement = "ignore" | "warn" | "error";
+export interface ValidationPolicy {
+    missingSection?: Enforcement;
+    emptyRequiredSection?: Enforcement;
+    wrongSectionKind?: Enforcement;
+    containerMissing?: Enforcement;
+    containerMultiple?: Enforcement;
+    containerOutsideText?: Enforcement;
+    duplicateSection?: Enforcement;
+    malformedTable?: Enforcement;
+    malformedOrderedTable?: Enforcement;
+    noneIsAcceptableContent?: boolean;
+}
+export type Severity = "info" | "warn" | "error";
+export type IssueCode = "ISSUES_ENVELOPE_PRESENT" | "CONTAINER_MISSING" | "CONTAINER_MULTIPLE" | "CONTAINER_OUTSIDE_TEXT" | "MISSING_SECTION" | "EMPTY_REQUIRED_SECTION" | "DUPLICATE_SECTION" | "WRONG_SECTION_KIND" | "MALFORMED_TABLE" | "MALFORMED_ORDERED_TABLE";
+export interface ValidationIssue {
+    code: IssueCode;
+    severity: Severity;
+    message: string;
+    sectionName?: string;
+    span?: {
+        start: number;
+        end: number;
+    };
+}
+export interface ValidationResult {
+    ok: boolean;
+    level: 0 | 1 | 2 | 3;
+    issues: ValidationIssue[];
+    stats?: {
+        detectedKind: "markdown" | "issues" | "sectioned" | "fenced";
+        sectionCount: number;
+        missingRequired: string[];
+        duplicates: string[];
+        container: {
+            fenceCount: number;
+            hasOutsideText: boolean;
+            fenceLangs: string[];
+        };
+    };
+}
+export type SectionKind = "text" | "list" | "ordered_list" | "table" | "ordered_table";
+export interface OutputSectionSpec {
+    name: string;
+    kind?: SectionKind;
+    required?: boolean;
+    columns?: string[];
+}
+/**
+ * @deprecated Use OutputSectionSpec
+ */
+export interface OfsSection extends OutputSectionSpec {
+    hint?: string;
+    emptyAllowed?: boolean;
+}
+export interface OfsTable {
+    columns: string[];
+    kind: "table" | "ordered_table";
+    by?: string;
+    required?: boolean;
+}
+export interface OutputFormatSpec {
+    sections: OutputSectionSpec[];
+    emptySectionValue?: string;
+    descriptorType?: "output_format_spec";
+    format?: "markdown";
+    sectionOrderMatters?: boolean;
+    tablesOptional?: boolean;
+    tables?: OfsTable[];
+}
+export interface MdNode {
+    title: string;
+    level: number;
+    key: string;
+    id?: string;
+    content_md: string;
+    children: MdNode[];
+}
+export interface MdOutline {
+    type: "md_outline";
+    nodes: MdNode[];
+}
+export interface ListItem {
+    text: string;
+    index?: number;
+    children: ListItem[];
+}
+export interface ParsedList {
+    kind: "list";
+    ordered: boolean;
+    items: ListItem[];
+}
+export interface ParsedTable {
+    kind: "table" | "ordered_table";
+    by?: string;
+    columns: string[];
+    rows: string[][];
+}
+export interface ExtractedResult {
+    outline: MdOutline;
+    sectionsByName: Record<string, {
+        nodeKey: string;
+        nodeLevel: number;
+        md: string;
+        list?: ParsedList;
+    }>;
+    tables: ParsedTable[];
+}
+export interface ProcessResponseResult {
+    ok: boolean;
+    strictness: any;
+    usedContainer: boolean;
+    innerMarkdown: string;
+    validation: ValidationResult;
+    extracted?: ExtractedResult;
+    issues: ValidationIssue[];
+    issuesEnvelope?: IssuesEnvelope;
+}
+export type DetectedKind = "flexmd_fence" | "flexdoc_json_fence" | "raw_flexmd" | "markdown_snippet" | "none";
+export interface DetectedObject {
+    kind: DetectedKind;
+    confidence: number;
+    start: number;
+    end: number;
+    raw: string;
+    inner?: string;
+}
+export interface IssuesEnvelope {
+    isIssuesEnvelope: boolean;
+    sections: Record<string, {
+        heading: string;
+        body: string;
+        bullets: string[];
+    }>;
+}

package/dist/validate/policy.d.ts

@@ -0,0 +1,10 @@
+import { Enforcement, SemiStrictPolicy } from "../strictness/types.js";
+import { ValidationIssue } from "./types.js";
+export declare function enforcementToSeverity(e: Enforcement): "error" | "warning";
+/**
+ * Decide whether to emit an issue:
+ * - "ignore" => return null
+ * - "warn"/"error" => return ValidationIssue with chosen severity
+ */
+export declare function makeIssue(policy: SemiStrictPolicy | undefined, key: keyof SemiStrictPolicy, fallback: Enforcement, issue: Omit<ValidationIssue, "severity">): ValidationIssue | null;
+export declare function hasErrors(issues: ValidationIssue[]): boolean;

package/dist/validate/policy.js

@@ -0,0 +1,17 @@
+export function enforcementToSeverity(e) {
+    return e === "error" ? "error" : "warning";
+}
+/**
+ * Decide whether to emit an issue:
+ * - "ignore" => return null
+ * - "warn"/"error" => return ValidationIssue with chosen severity
+ */
+export function makeIssue(policy, key, fallback, issue) {
+    const enforcement = (policy?.[key] ?? fallback);
+    if (enforcement === "ignore")
+        return null;
+    return { severity: enforcementToSeverity(enforcement), ...issue };
+}
+export function hasErrors(issues) {
+    return issues.some(i => i.severity === "error");
+}

package/dist/validate/types.d.ts

@@ -0,0 +1,11 @@
+export type ValidationSeverity = "error" | "warning";
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+}

package/dist/validate/types.js

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

package/dist/validate/validate.d.ts

@@ -0,0 +1,2 @@
+import { OutputFormatSpec, ValidationPolicy, ValidationResult } from "../types.js";
+export declare function validateMarkdownAgainstOfs(input: string, spec: OutputFormatSpec, level: 0 | 1 | 2 | 3, policyOverride?: ValidationPolicy): ValidationResult;