flex-md 4.4.9 → 4.5.0

package/dist/detect/json/detectMarkdown.js

@@ -8,22 +8,63 @@
  * Notes:
  * - This is heuristic by design; tune thresholds as you learn your data.
  */
+import { logger } from "../../logger.js";
 const SINGLE_FENCE_BLOCK_RE = /^```([a-zA-Z0-9_-]+)?([^\n]*)\n([\s\S]*?)\n```$/;
 const FENCE_OPEN_RE = /(^|\n)```/g;
 export function detectMarkdown(text) {
+    logger.debug("Starting markdown detection", {
+        inputType: typeof text,
+        inputLength: typeof text === "string" ? text.length : JSON.stringify(text ?? "").length
+    });
     const reasons = [];
     const raw = typeof text === "string" ? text : JSON.stringify(text ?? "");
     const s = raw.replace(/\r\n/g, "\n");
+    logger.verbose("Input normalized for processing", {
+        originalType: typeof text,
+        normalizedLength: s.length,
+        hasNewlines: s.includes('\n')
+    });
     const codeFences = [...s.matchAll(FENCE_OPEN_RE)].length;
+    logger.debug("Code fence analysis", {
+        totalFences: codeFences,
+        fenceRegex: FENCE_OPEN_RE.source
+    });
     // Framed detection (single fenced block)
     const m = s.match(SINGLE_FENCE_BLOCK_RE);
     const isFramed = !!m && codeFences === 2;
     const frameLanguage = isFramed ? (m?.[1] ?? null) : null;
-    if (isFramed)
+    logger.debug("Framed markdown detection", {
+        regexMatch: !!m,
+        expectedFences: 2,
+        actualFences: codeFences,
+        isFramed,
+        frameLanguage,
+        regexGroups: m ? {
+            fullMatch: m[0],
+            language: m[1],
+            content: m[3]?.substring(0, 100) + (m[3]?.length > 100 ? '...' : '')
+        } : null
+    });
+    if (isFramed) {
         reasons.push("Single fenced code block detected (framed payload).");
-    else if (codeFences > 1)
+        logger.info("Detected framed markdown", { language: frameLanguage });
+    }
+    else if (codeFences > 2) {
         reasons.push("Multiple fenced code blocks detected.");
+        logger.debug("Multiple fences detected, not treating as single framed block", { fenceCount: codeFences });
+    }
+    else if (codeFences === 1) {
+        reasons.push("Single fence marker found but not properly framed.");
+        logger.debug("Single fence found but regex didn't match", {
+            regex: SINGLE_FENCE_BLOCK_RE.source,
+            hasMatch: !!m
+        });
+    }
+    else {
+        logger.debug("No fence markers detected");
+    }
     const lines = s.split("\n");
+    logger.verbose("Line-by-line analysis started", { totalLines: lines.length });
     const atxHeadings = lines.filter((l) => /^#{1,6}\s+\S/.test(l.trim())).length;
     let setextHeadings = 0;
     for (let i = 0; i < lines.length - 1; i++) {
@@ -48,32 +89,70 @@ export function detectMarkdown(text) {
         (s.match(/__[^_\n]+__/g) ?? []).length +
         (s.match(/(^|[^*])\*[^*\n]+\*([^*]|$)/g) ?? []).length +
         (s.match(/(^|[^_])_[^_\n]+_([^_]|$)/g) ?? []).length;
+    logger.debug("Markdown structure analysis", {
+        atxHeadings,
+        setextHeadings,
+        totalHeadings: headings,
+        unorderedListLines,
+        orderedListLines,
+        tableRows,
+        inlineCodeSpans,
+        mdLinks,
+        emphasisTokens
+    });
     // Heuristic decision rules
     const hasList = unorderedListLines + orderedListLines >= 2;
     const hasTable = tableRows >= 2;
     const hasOtherSignals = inlineCodeSpans + mdLinks + emphasisTokens >= 2;
+    logger.debug("Heuristic analysis", {
+        hasList,
+        hasTable,
+        hasOtherSignals,
+        listThreshold: 2,
+        tableThreshold: 2,
+        otherSignalsThreshold: 2
+    });
     let isMarkdownLikely = false;
     if (isFramed) {
         isMarkdownLikely = true;
+        logger.debug("Markdown likelihood determined: framed content is always considered markdown");
     }
     else if (headings >= 2) {
         isMarkdownLikely = true;
         reasons.push(`Detected ${headings} markdown heading(s) (>=2).`);
+        logger.debug("Markdown likelihood: sufficient headings detected", { headingCount: headings });
     }
     else if (headings >= 1 && (hasList || hasTable)) {
         isMarkdownLikely = true;
         reasons.push(`Detected heading(s) plus ${hasList ? "list" : "table"} structure.`);
+        logger.debug("Markdown likelihood: heading plus structural element", {
+            hasHeading: headings >= 1,
+            hasList,
+            hasTable
+        });
     }
     else if ((hasList && hasTable) || (hasTable && hasOtherSignals) || (hasList && hasOtherSignals)) {
         isMarkdownLikely = true;
         reasons.push("Detected multiple markdown structural signals (lists/tables/links/code/emphasis).");
+        logger.debug("Markdown likelihood: multiple structural signals", {
+            listAndTable: hasList && hasTable,
+            tableAndOther: hasTable && hasOtherSignals,
+            listAndOther: hasList && hasOtherSignals
+        });
     }
     else {
         reasons.push("Insufficient markdown structure signals; treating as plain text.");
+        logger.debug("Markdown likelihood: insufficient signals, treating as plain text", {
+            headings,
+            hasList,
+            hasTable,
+            hasOtherSignals
+        });
     }
     if (/^\s*#{1,6}\s+\S/.test(lines[0] ?? "")) {
         reasons.push("Text starts with an ATX heading (#...).");
         isMarkdownLikely = true;
+        logger.debug("Additional check: starts with heading, upgrading to markdown");
     }
     return {
         isMarkdownLikely,
@@ -137,11 +216,32 @@ export function forceWrapAsMarkdown(plainText, opts) {
  * - Else: wrap as markdown under a chosen heading
  */
 export function normalizeForFlexMd(input, opts) {
+    logger.info("Starting Flex-MD normalization", {
+        inputType: typeof input,
+        inputLength: typeof input === "string" ? input.length : JSON.stringify(input ?? "").length,
+        options: opts
+    });
     const raw = typeof input === "string" ? input : JSON.stringify(input ?? "");
     const detection = detectMarkdown(raw);
+    logger.debug("Detection completed", {
+        isFramed: detection.isFramed,
+        isMarkdownLikely: detection.isMarkdownLikely,
+        frameLanguage: detection.frameLanguage,
+        reasons: detection.reasons
+    });
     // 1) Strip if framed
     const { stripped, wasFramed, language } = stripSingleFence(raw);
+    logger.debug("Strip fence check", {
+        wasFramed,
+        language,
+        strippedLength: stripped.length,
+        originalLength: raw.length
+    });
     if (wasFramed) {
+        logger.info("Normalization: stripped framed markdown", {
+            language,
+            contentLength: stripped.length
+        });
         return {
             normalizedText: stripped,
             detection,
@@ -152,6 +252,9 @@ export function normalizeForFlexMd(input, opts) {
     }
     // 2) Keep if markdown-likely
     if (detection.isMarkdownLikely) {
+        logger.info("Normalization: keeping as-is (markdown-likely)", {
+            reasons: detection.reasons
+        });
         return {
             normalizedText: raw,
             detection,
@@ -161,9 +264,20 @@ export function normalizeForFlexMd(input, opts) {
         };
     }
     // 3) Wrap if not markdown-likely
+    const fallbackHeading = opts?.fallbackHeading ?? "Full Answer";
+    const fallbackLevel = opts?.fallbackHeadingLevel ?? 3;
+    logger.info("Normalization: wrapping as markdown", {
+        fallbackHeading,
+        fallbackLevel,
+        reasons: detection.reasons
+    });
     const wrapped = forceWrapAsMarkdown(raw, {
-        heading: opts?.fallbackHeading ?? "Full Answer",
-        level: opts?.fallbackHeadingLevel ?? 3,
+        heading: fallbackHeading,
+        level: fallbackLevel,
+    });
+    logger.debug("Wrapping completed", {
+        wrappedLength: wrapped.length,
+        originalLength: raw.length
     });
     return {
         normalizedText: wrapped,

package/dist/index.cjs

@@ -14,10 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.jsonToMarkdown = exports.Schema = exports.MarkdownParser = exports.JSONTransformer = exports.enforceFlexMd = exports.repairToMarkdownLevel = exports.detectResponseKind = exports.buildIssuesEnvelopeAuto = exports.buildIssuesEnvelope = exports.parseIssuesEnvelope = exports.processResponseMarkdown = exports.extractFromMarkdown = exports.checkConnection = exports.hasFlexMdContract = exports.checkCompliance = exports.validateMarkdownAgainstOfs = exports.enrichInstructionsWithFlexMd = exports.enrichInstructions = exports.buildMarkdownGuidance = exports.stringifyOutputFormatSpec = exports.recall = exports.remember = exports.transformWithOfs = exports.ofsToSchema = exports.validateFormat = exports.parseOutputFormatSpec = exports.buildOutline = void 0;
+exports.jsonToMarkdown = exports.Schema = exports.MarkdownParser = exports.JSONTransformer = exports.enforceFlexMd = exports.repairToMarkdownLevel = exports.detectResponseKind = exports.buildIssuesEnvelopeAuto = exports.buildIssuesEnvelope = exports.parseIssuesEnvelope = exports.processResponseMarkdown = exports.extractFromMarkdown = exports.checkConnection = exports.hasFlexMdContract = exports.checkCompliance = exports.validateMarkdownAgainstOfs = exports.enrichInstructionsWithFlexMd = exports.enrichInstructions = exports.buildMarkdownGuidance = exports.stringifyOutputFormatSpec = exports.recall = exports.remember = exports.transformWithOfs = exports.ofsToSchema = exports.validateFormat = exports.parseOutputFormatSpec = exports.buildOutline = exports.logger = void 0;
 // Core SFMD Types
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./strictness/types.js"), exports);
+// Logging
+var logger_js_1 = require("./logger.js");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_js_1.logger; } });
 // Shared MD Parsing
 __exportStar(require("./md/parse.js"), exports);
 var outline_js_1 = require("./md/outline.js");

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./strictness/types.js";
+export { logger } from "./logger.js";
 export * from "./md/parse.js";
 export { buildOutline } from "./md/outline.js";
 export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 // Core SFMD Types
 export * from "./types.js";
 export * from "./strictness/types.js";
+// Logging
+export { logger } from "./logger.js";
 // Shared MD Parsing
 export * from "./md/parse.js";
 export { buildOutline } from "./md/outline.js";

package/dist/logger.d.ts

@@ -0,0 +1,4 @@
+import { Logger } from 'micro-logs';
+declare const threshold: "error" | "warn" | "info" | "verbose" | "debug";
+export declare const logger: Logger;
+export { threshold };

package/dist/logger.js

@@ -0,0 +1,19 @@
+import { Logger } from 'micro-logs';
+// Get DEBUG_LEVEL from environment, default to 'info'
+const debugLevel = process.env.DEBUG_LEVEL || 'info';
+// Map string levels to micro-logs levels
+const levelMapping = {
+    'verbose': 'verbose',
+    'debug': 'debug',
+    'info': 'info',
+    'warn': 'warn',
+    'error': 'error'
+};
+// Default to 'info' if invalid level provided
+const threshold = levelMapping[debugLevel.toLowerCase()] || 'info';
+export const logger = new Logger({
+    packageName: 'flex-md',
+    envPrefix: 'FLEX_MD',
+    debugNamespace: 'flex-md:*'
+});
+export { threshold };

package/dist/ofs/adapter.js

@@ -4,6 +4,7 @@ import { parseHeadingsAndSections, extractBullets, parseMarkdownTable, normalize
 import { normalizeMarkdownInput } from "../md/normalize.js";
 import { toCamelCase } from "nx-helpers";
 import { markdownToJson as autoMarkdownToJson } from "nx-json-parser";
+import { logger } from "../logger.js";
 /**
  * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
  */
@@ -53,11 +54,27 @@ export function ofsToSchema(spec) {
  * If no spec is provided, it attempts to infer it from the markdown (autospecs).
  */
 export function transformWithOfs(md, specOrRecallId) {
+    logger.info("Starting Flex-MD transformation", {
+        inputLength: md.length,
+        hasSpec: !!specOrRecallId,
+        specType: specOrRecallId ? typeof specOrRecallId : 'none'
+    });
     // 0. Normalize input (handle literal \n common in LLM outputs)
     const normalizedMd = normalizeMarkdownInput(md);
+    logger.debug("Input normalization", {
+        originalLength: md.length,
+        normalizedLength: normalizedMd.length,
+        changed: md !== normalizedMd
+    });
     // 1. Automatic parsing (Dual-Response) using nx-json-parser
+    logger.debug("Starting automatic parsing with nx-json-parser");
     const parsedOutput = autoMarkdownToJson(normalizedMd);
+    logger.debug("Automatic parsing completed", {
+        parsedKeys: Object.keys(parsedOutput),
+        parsedKeyCount: Object.keys(parsedOutput).length
+    });
     if (!specOrRecallId) {
+        logger.info("No spec provided, returning parsed output only");
         return {
             parsedOutput,
             contractOutput: null,
@@ -68,8 +85,10 @@ export function transformWithOfs(md, specOrRecallId) {
     }
     let spec;
     if (typeof specOrRecallId === "string") {
+        logger.debug("Recalling spec from memory", { recallId: specOrRecallId });
         const recalled = recall(specOrRecallId);
         if (!recalled) {
+            logger.warn("Recall ID not found", { recallId: specOrRecallId });
             return {
                 parsedOutput,
                 contractOutput: null,
@@ -79,41 +98,79 @@ export function transformWithOfs(md, specOrRecallId) {
             };
         }
         spec = recalled;
+        logger.debug("Spec recalled successfully", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
     }
     else {
         spec = specOrRecallId;
+        logger.debug("Using provided spec directly", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
     }
     // 2. Parse sections using Flex-MD parser for the contract mapping
     const bulletNames = spec.sections.map(s => s.name);
+    logger.debug("Starting section parsing", {
+        expectedSections: bulletNames,
+        sectionCount: bulletNames.length
+    });
     // Note: We use the local headings parser to find the specific sections defined in the spec
     const parsedSections = parseHeadingsAndSections(normalizedMd, { bulletNames });
+    logger.debug("Section parsing completed", {
+        foundSections: parsedSections.map(s => s.heading.name),
+        foundCount: parsedSections.length
+    });
     const parsedObj = {};
     for (const sectionSpec of spec.sections) {
         const normName = normalizeName(sectionSpec.name);
         const found = parsedSections.find(s => normalizeName(s.heading.name) === normName);
+        logger.verbose(`Processing section "${sectionSpec.name}"`, {
+            normalizedName: normName,
+            found: !!found,
+            kind: sectionSpec.kind,
+            hasColumns: !!sectionSpec.columns
+        });
         if (found) {
             let value;
             switch (sectionSpec.kind) {
                 case "list":
                 case "ordered_list":
                     value = extractBullets(found.body);
+                    logger.debug(`Extracted bullets for "${sectionSpec.name}"`, {
+                        bulletCount: Array.isArray(value) ? value.length : 'unknown'
+                    });
                     break;
                 case "table":
                 case "ordered_table":
                     if (sectionSpec.columns) {
                         value = parseMarkdownTable(found.body, sectionSpec.columns);
+                        logger.debug(`Parsed table for "${sectionSpec.name}"`, {
+                            columns: sectionSpec.columns,
+                            rowCount: Array.isArray(value) ? value.length : 'unknown'
+                        });
                     }
                     else {
                         value = found.body.trim();
+                        logger.debug(`Using raw body for table "${sectionSpec.name}" (no columns specified)`);
                     }
                     break;
                 default:
                     value = found.body.trim();
+                    logger.debug(`Using trimmed body for "${sectionSpec.name}"`);
                     break;
             }
             parsedObj[sectionSpec.name] = value;
         }
+        else {
+            logger.warn(`Section "${sectionSpec.name}" not found in markdown`);
+        }
     }
+    logger.debug("Contract parsing completed", {
+        parsedKeys: Object.keys(parsedObj),
+        parsedKeyCount: Object.keys(parsedObj).length
+    });
     // 3. Transform using nx-md-parser (latest v2.2.0) for schema validation and fixing
     const schema = ofsToSchema(spec);
     const transformer = new JSONTransformer(schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.4.9",
+  "version": "4.5.0",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -52,6 +52,7 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
+    "micro-logs": "^1.0.0",
     "nd": "^1.2.0",
     "nx-helpers": "^1.5.0",
     "nx-json-parser": "^1.2.1",