flex-md 3.2.0 → 3.5.0

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

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

package/dist/__tests__/structural.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { buildOutline, checkConnection } from "../index.js";
+describe("Structural Diagnostics", () => {
+    describe("===key support", () => {
+        it("should parse ===key as a top-level section", () => {
+            const md = `===skills\nThis is the skills section.\n\n## Subskill\nDetails.`;
+            const outline = buildOutline(md);
+            expect(outline.nodes).toHaveLength(1);
+            expect(outline.nodes[0].title).toBe("skills");
+            expect(outline.nodes[0].children).toHaveLength(1);
+            expect(outline.nodes[0].children[0].title).toBe("Subskill");
+        });
+    });
+    describe("checkConnection", () => {
+        it("should find a section by name", () => {
+            const md = `# Overview\n## Details\n===skills\nContent.`;
+            const res = checkConnection(md, "skills");
+            expect(res.connected).toBe(true);
+            expect(res.path).toContain("skills");
+        });
+        it("should fail gracefully for missing sections", () => {
+            const md = `# Overview`;
+            const res = checkConnection(md, "missing");
+            expect(res.connected).toBe(false);
+            expect(res.suggestion).toContain("Overview");
+        });
+    });
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { checkCompliance, checkConnection } from "../index.js";
+const [, , command, ...args] = process.argv;
+async function main() {
+    if (!command || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    try {
+        switch (command) {
+            case "check":
+                await handleCheck(args);
+                break;
+            case "diagnose":
+                await handleDiagnose(args);
+                break;
+            case "create":
+                await handleCreate(args);
+                break;
+            case "sync":
+                await handleSync(args);
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp();
+                process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+Flex-MD CLI v3.2.0
+
+Usage:
+  flex-md <command> [options]
+
+Commands:
+  check <file> [--level L2]    Check compliance of a markdown file.
+  diagnose <file> <key>        Diagnose if a specific key/section is connected.
+  create <file> <key>          Create a new section (folder/file simulation).
+  sync <source> <target>       Sync content from source to target.
+
+Options:
+  --help, -h                  Show this help message.
+    `);
+}
+async function handleCheck(args) {
+    const file = args[0];
+    if (!file)
+        throw new Error("Missing file argument.");
+    const level = (args.includes("--level") ? args[args.indexOf("--level") + 1] : "L2");
+    const content = readFileSync(resolve(file), "utf-8");
+    const result = await checkCompliance(content, level);
+    if (result.meetsCompliance) {
+        console.log("✅ Content meets compliance.");
+    }
+    else {
+        console.log("❌ Content does not meet compliance.");
+        result.issues.forEach(i => console.log(`  - [${i.severity}] ${i.description}`));
+        console.log("\nSuggestions:");
+        result.suggestions.forEach(s => console.log(`  - ${s}`));
+    }
+}
+async function handleDiagnose(args) {
+    const file = args[0];
+    const key = args[1];
+    if (!file || !key)
+        throw new Error("Usage: flex-md diagnose <file> <key>");
+    if (!existsSync(file))
+        throw new Error(`File not found: ${file}`);
+    const content = readFileSync(resolve(file), "utf-8");
+    const result = checkConnection(content, key);
+    if (result.connected) {
+        console.log(`✅ Key "${key}" found at path: ${result.path?.join(" -> ")}`);
+    }
+    else {
+        console.log(`❌ Key "${key}" not connected.`);
+        console.log(`Suggestion: ${result.suggestion}`);
+    }
+}
+async function handleCreate(args) {
+    const file = args[0];
+    const key = args[1];
+    if (!file || !key)
+        throw new Error("Usage: flex-md create <file> <key>");
+    const content = existsSync(file) ? readFileSync(file, "utf-8") : "";
+    const newContent = content + `\n\n## ${key}\n\n[Content for ${key}]\n`;
+    writeFileSync(file, newContent);
+    console.log(`✅ Section "${key}" created in ${file}`);
+}
+async function handleSync(args) {
+    const source = args[0];
+    const target = args[1];
+    if (!source || !target)
+        throw new Error("Usage: flex-md sync <source> <target>");
+    if (!existsSync(source))
+        throw new Error(`Source file not found: ${source}`);
+    const content = readFileSync(source, "utf-8");
+    writeFileSync(target, content);
+    console.log(`✅ Content synced from ${source} to ${target}`);
+}
+main();

package/dist/index.d.ts

@@ -1,11 +1,13 @@
 export * from "./types.js";
 export * from "./strictness/types.js";
 export * from "./md/parse.js";
+export { buildOutline } from "./md/outline.js";
 export { parseOutputFormatSpec, validateFormat } from "./ofs/parser.js";
 export { stringifyOutputFormatSpec } from "./ofs/stringify.js";
 export { buildMarkdownGuidance, enrichInstructions, enrichInstructionsWithFlexMd } from "./ofs/enricher.js";
 export { validateMarkdownAgainstOfs } from "./validate/validate.js";
 export { checkCompliance, hasFlexMdContract } from "./validate/compliance.js";
+export { checkConnection } from "./validate/connection.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

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

package/dist/md/outline.d.ts

@@ -1,6 +1,9 @@
-import type { MdOutline } from "../types.js";
+import { MdOutline } from "../types.js";
 /**
- * Builds a nested outline tree from Markdown headings.
- * Supports any heading level and captures content between headings.
+ * Builds a nested tree of headings (outline) from Markdown text.
  */
 export declare function buildOutline(md: string): MdOutline;
+/**
+ * Slugifies a string into an internal key.
+ */
+export declare function slugify(text: string): string;

package/dist/md/outline.js

@@ -1,67 +1,45 @@
+import { parseHeadingsAndSections } from "./parse.js";
 /**
- * Builds a nested outline tree from Markdown headings.
- * Supports any heading level and captures content between headings.
+ * Builds a nested tree of headings (outline) from Markdown text.
  */
 export function buildOutline(md) {
-    const lines = md.split("\n");
-    const headings = [];
-    for (let i = 0; i < lines.length; i++) {
-        const m = (lines[i] ?? "").match(/^(#{1,6})\s+(.+?)\s*$/);
-        if (m) {
-            headings.push({ idx: i, level: m[1].length, title: cleanTitle(m[2]) });
-        }
-    }
-    if (!headings.length) {
-        return { type: "md_outline", nodes: [] };
-    }
-    const nodes = [];
+    const sections = parseHeadingsAndSections(md);
+    const roots = [];
     const stack = [];
-    for (let h = 0; h < headings.length; h++) {
-        const cur = headings[h];
-        const next = headings[h + 1];
-        const contentStart = cur.idx + 1;
-        const contentEnd = next ? next.idx : lines.length;
-        const content_md = lines.slice(contentStart, contentEnd).join("\n").trimEnd() + "\n";
+    for (const s of sections) {
+        const h = s.heading;
         const node = {
-            title: cur.title,
-            level: cur.level,
-            key: "",
-            content_md,
+            title: h.name,
+            level: h.level,
+            key: h.norm,
+            content_md: s.body,
             children: []
         };
-        while (stack.length && stack[stack.length - 1].level >= node.level) {
+        // Pop from stack until we find a parent (level < node.level)
+        while (stack.length > 0 && stack[stack.length - 1].level >= node.level) {
             stack.pop();
         }
-        if (!stack.length) {
-            nodes.push(node);
+        if (stack.length === 0) {
+            roots.push(node);
         }
         else {
             stack[stack.length - 1].children.push(node);
         }
         stack.push(node);
     }
-    assignKeys(nodes);
-    return { type: "md_outline", nodes };
-}
-function cleanTitle(t) {
-    return t.trim().replace(/[:\-–—]\s*$/, "").trim();
-}
-function slugify(t) {
-    return t.toLowerCase()
-        .replace(/[:\-–—]+$/g, "")
-        .replace(/\s+/g, "_")
-        .replace(/[^a-z0-9_]/g, "")
-        .replace(/_+/g, "_")
-        .replace(/^_+|_+$/g, "");
-}
-function assignKeys(nodes) {
-    const seen = new Map();
-    const visit = (n) => {
-        const base = slugify(n.title) || "section";
-        const count = (seen.get(base) ?? 0) + 1;
-        seen.set(base, count);
-        n.key = count === 1 ? base : `${base}__${count}`;
-        n.children.forEach(visit);
+    return {
+        type: "md_outline",
+        nodes: roots
     };
-    nodes.forEach(visit);
+}
+/**
+ * Slugifies a string into an internal key.
+ */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/[\s_-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
 }

package/dist/md/parse.js

@@ -28,17 +28,28 @@ export function extractFencedBlocks(text) {
     return blocks;
 }
 export function parseHeadingsAndSections(md) {
-    const rx = /^(#{1,6})\s+(.+?)\s*$/gm;
+    // Standard headings #... and alternative ===key
+    const rx = /^((?:#{1,6})\s+(.+?)\s*|===(.+?)\s*)$/gm;
     const headings = [];
     let m;
     while ((m = rx.exec(md)) !== null) {
-        const hashes = m[1] ?? "";
-        const name = (m[2] ?? "").trim();
+        const full = m[1] ?? "";
+        let level;
+        let name;
+        if (full.startsWith("===")) {
+            level = 1; // Treat ===key as a top-level heading
+            name = (m[3] ?? "").trim();
+        }
+        else {
+            const hashes = (full.match(/^#+/) ?? [""])[0];
+            level = hashes.length;
+            name = (m[2] ?? "").trim();
+        }
         const raw = m[0] ?? "";
         const start = m.index;
         const end = start + raw.length;
         headings.push({
-            level: hashes.length,
+            level,
             raw,
             name,
             norm: normalizeName(name),

package/dist/validate/connection.d.ts

@@ -0,0 +1,12 @@
+export interface ConnectionResult {
+    connected: boolean;
+    key: string;
+    normalizedKey: string;
+    path?: string[];
+    alternativeMatches?: string[];
+    suggestion?: string;
+}
+/**
+ * Checks if a specific key (section) is "connected" in the given markdown.
+ */
+export declare function checkConnection(md: string, key: string): ConnectionResult;

package/dist/validate/connection.js

@@ -0,0 +1,44 @@
+import { buildOutline } from "../md/outline.js";
+import { normalizeName } from "../md/parse.js";
+/**
+ * Checks if a specific key (section) is "connected" in the given markdown.
+ */
+export function checkConnection(md, key) {
+    const outline = buildOutline(md);
+    const normKey = 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "3.2.0",
+  "version": "3.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": "",
@@ -20,6 +20,9 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "flex-md": "./dist/cli/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -39,7 +42,8 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@types/node": "^25.0.3",
     "typescript": "^5.6.3",
     "vitest": "^4.0.16"
   }
-}
+}