flex-md 3.5.0 → 4.1.0

package/README.md

@@ -1,17 +1,31 @@
-# Flex-MD (v3.0) — Markdown Output Contract
+# Flex-MD (v4.0) — Markdown Output Contract with Smart Token Estimation
 
 Flex-MD is a TypeScript library for building and enforcing **Markdown Output Contracts** with LLMs. It treats Markdown as a semi-structured data format, allowing you to define required sections, list types, and tables while maintaining 100% standard Markdown compatibility.
 
-Version 3.0 introduces the **Detect-Repair-Enforce** pipeline, ensuring LLM responses are coerced into compliant structures before being parsed.
+**What's New in v4.0:**
+- 🎯 **Automatic Token Estimation**: Calculate `max_tokens` directly from your spec
+- 📏 **System Parts Protocol**: Standardized size hints that guide LLMs AND enable token prediction
+- 🧠 **Smart Toolbox**: Cognitive cost analysis, confidence scoring, and improvement detection
+- 🔧 **Auto-Fix**: Automatically improve specs with one command
 
 ## Key Features
 
+### Core (v3.0)
 - **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.
 
+### Smart Features (v4.0)
+- **Token Estimation**: Automatically calculate `max_tokens` for API calls based on your spec
+- **System Parts**: Structured instruction patterns (`Length: 2-3 paragraphs`, `Items: 3-5`) that guide LLMs and enable estimation
+- **Compliance Checking**: Validate specs meet quality standards (L0-L3 compliance levels)
+- **Cognitive Cost Analysis**: Measure how much effort your spec requires to write/maintain
+- **Confidence Scoring**: Know how accurate your token estimates will be
+- **Improvement Detection**: Find issues and get actionable suggestions
+- **Auto-Fix**: Apply improvements automatically
+
 ## Installation
 
 ```bash
@@ -20,29 +34,49 @@ npm install flex-md
 
 ## Quick Start
 
-### 1. Define your Output Format Spec (OFS)
+### 1. Define your Output Format Spec (OFS) with System Parts
 
 ```typescript
-import { parseOutputFormatSpec } from 'flex-md';
+import { parseOutputFormatSpec, getMaxTokens } from 'flex-md';
 
 const spec = parseOutputFormatSpec(`
 ## Output format
 - Short answer — text (required)
+  Length: 1-2 sentences. Be concise and direct.
+
 - Reasoning — ordered list (required)
+  Items: 3-5. Explain your logic step by step.
+
 - Assumptions — list (optional)
+  Items: at least 2. List any key assumptions made.
 
 empty sections:
 - If a section is empty, write \`None\`.
 `);
+
+// Automatically estimate max_tokens needed
+const maxTokens = getMaxTokens(spec);
+console.log(`Estimated max_tokens: ${maxTokens}`); // ~650
 ```
 
-### 2. Generate Prompt Guidance
+### 2. Use in Your LLM API Call
 
 ```typescript
-import { buildMarkdownGuidance } from 'flex-md';
-
-const guidance = buildMarkdownGuidance(spec, { level: 1 });
-// Output: "Reply in Markdown. Include these headings... If a section is empty, write 'None'."
+const response = await fetch('https://api.anthropic.com/v1/messages', {
+  method: 'POST',
+  headers: { 
+    'Content-Type': 'application/json',
+    'x-api-key': API_KEY 
+  },
+  body: JSON.stringify({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: maxTokens,  // Automatically calculated!
+    messages: [{
+      role: 'user',
+      content: yourPrompt + '\n\n' + buildMarkdownGuidance(spec)
+    }]
+  })
+});
 ```
 
 ### 3. Enforce the Contract
@@ -50,47 +84,201 @@ const guidance = buildMarkdownGuidance(spec, { level: 1 });
 ```typescript
 import { enforceFlexMd } from 'flex-md';
 
-const llmResponse = "I think... ## Short answer \n Yes. ## Reasoning \n 1. Logic";
-const result = enforceFlexMd(llmResponse, spec, { level: 1 });
+const llmResponse = await response.json();
+const result = enforceFlexMd(llmResponse.content[0].text, spec, { level: 2 });
 
 if (result.ok) {
   console.log(result.extracted.sectionsByName["Short answer"].md);
+  console.log(result.extracted.sectionsByName["Reasoning"].md);
 } else {
-  // result.outputText will contain the Issues Envelope if strictness level >= 1
-  console.log(result.outputText); 
+  console.log(result.outputText); // Issues Envelope
 }
 ```
 
-### 4. Dynamic Instructions Output Format Blocks
+## System Parts Protocol
 
-You can also define your spec as a plain JavaScript object and generate the formal "Instructions Block" for your LLM prompts.
+System Parts are structured prefixes in section instructions that serve dual purposes:
+1. **Guide the LLM** on expected output size
+2. **Enable token estimation** for `max_tokens` calculation
+
+### Syntax
+
+```
+[SYSTEM_PART]. [OPTIONAL_GUIDANCE]
+```
 
+**Examples:**
 ```typescript
-import { stringifyOutputFormatSpec } from 'flex-md';
+// Text sections
+"Length: 2-3 paragraphs. Provide detailed analysis."
+"Length: brief. Keep it short."
 
-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."
-    }
-  ]
-};
+// Lists
+"Items: 3-5. Focus on key insights."
+"Items: at least 3. Be comprehensive."
 
-const instructionsBlock = stringifyOutputFormatSpec(spec);
-// Output will include the ## Output format (Markdown) header, descriptions, and instructions.
+// Tables
+"Rows: 5-7, Columns: 3. Include metrics."
+
+// Code
+"Lines: 20-30. Include error handling."
+"Lines: ~50. Provide complete example."
 ```
 
-## Strictness Levels
+### Allowed Values
+
+| Section Type | System Part Pattern | Examples |
+|--------------|-------------------|----------|
+| **text** | `Length: <value>` | `brief`, `moderate`, `detailed`, `extensive`, `1-2 sentences`, `2-3 paragraphs` |
+| **list** | `Items: <value>` | `3`, `3-5`, `at least 3` |
+| **table** | `Rows: <value>, Columns: <value>` | `Rows: 5, Columns: 3`, `Rows: 3-5, Columns: 4` |
+| **code** | `Lines: <value>` | `20`, `15-25`, `~50` |
+
+See [System Parts Guide](./docs/system-parts.md) for complete reference.
+
+## Compliance Levels (for Spec Authors)
+
+Compliance levels measure how much detail you provide in system parts:
+
+| Level | Detail | Cognitive Load | Token Estimation Accuracy |
+|-------|--------|---------------|--------------------------|
+| **L0** | No system parts | None | Fallback (~±40%) |
+| **L1** | Simple values | Minimal | Basic (~±30%) |
+| **L2** | Ranges allowed | Low | Good (~±20%) |
+| **L3** | Full spec with "at least", "~" | Medium | Precise (~±10%) |
+
+**L2 is recommended** for most use cases - good balance of effort and accuracy.
+
+### Examples by Level
+
+```typescript
+// L0 - No system parts (fallback estimation)
+"Just provide a summary."
+
+// L1 - Simple values
+"Length: brief. Provide a summary."
+"Items: 3. List the main points."
+
+// L2 - Ranges
+"Length: 2-3 paragraphs. Provide detailed analysis."
+"Items: 3-5. List key insights."
+
+// L3 - Full specification
+"Items: at least 5. Include all relevant factors."
+"Lines: ~50. Provide a complete working example."
+```
+
+## Smart Toolbox
+
+### Token Estimation
+
+```typescript
+import { getMaxTokens, estimateSpecTokens } from 'flex-md';
+
+// Quick estimate
+const maxTokens = getMaxTokens(spec);
+
+// Detailed estimate with options
+const estimate = estimateSpecTokens(spec, {
+  includeOptional: true,
+  safetyMultiplier: 1.3,
+  strategy: 'average'  // 'conservative' | 'average' | 'generous'
+});
+
+console.log(estimate);
+// {
+//   total: { estimated: 650, min: 520, max: 780, confidence: 'high' },
+//   bySectionName: { ... },
+//   overhead: 60
+// }
+```
+
+### Compliance Checking
+
+```typescript
+import { checkCompliance, formatComplianceReport } from 'flex-md';
+
+const report = checkCompliance(spec, 2); // Check if meets L2
+
+console.log(formatComplianceReport(report));
+// Shows which sections need improvement to meet target level
+```
+
+### Confidence Scoring
+
+```typescript
+import { calculateConfidence } from 'flex-md';
+
+const confidence = calculateConfidence(spec);
+
+console.log(`Confidence: ${confidence.grade} (${confidence.overall}%)`);
+console.log('Recommendations:', confidence.recommendations);
+// Grade: B (82%)
+// Recommendations: ["Good confidence, but can be improved", ...]
+```
+
+### Cognitive Cost Analysis
+
+```typescript
+import { calculateCognitiveCost } from 'flex-md';
+
+const cost = calculateCognitiveCost(spec);
+
+console.log(`Cost: ${cost.totalCost}/100`);
+console.log(`Assessment: ${cost.recommendation}`);
+// Cost: 28/100
+// Assessment: "Moderate cognitive load - reasonable effort required"
+```
+
+### Improvement Detection
+
+```typescript
+import { detectImprovements, formatImprovementReport, autoFix } from 'flex-md';
+
+// Detect issues and opportunities
+const analysis = detectImprovements(spec, 2);
+console.log(formatImprovementReport(analysis));
+
+// Auto-fix quick wins
+const fixResult = autoFix(spec, analysis.improvements, {
+  applyQuickWinsOnly: true
+});
+
+console.log(fixResult.summary);
+// "Applied 4 fixes, skipped 1"
+```
+
+### Complete Smart Analysis
+
+```typescript
+import { analyzeSpec, formatSmartReport } from 'flex-md';
+
+const analysis = analyzeSpec(spec, 2);
+console.log(formatSmartReport(analysis));
+```
+
+**Output:**
+```
+╔═══════════════════════════════════════════════════╗
+║         FLEX-MD SMART ANALYSIS REPORT            ║
+╚═══════════════════════════════════════════════════╝
+
+📊 SUMMARY DASHBOARD
+──────────────────────────────────────────────────
+Compliance:      ✓ L2 PASS
+Confidence:      B (82%)
+Cognitive Cost:  28/100
+Token Estimate:  650 tokens
+
+💡 RECOMMENDATIONS
+──────────────────────────────────────────────────
+🟢 Low Priority:
+   • Good confidence, but can be improved
+     → Upgrade a few sections to L3 for better precision
+...
+```
+
+## Strictness Levels (for LLM Output Enforcement)
 
 | Level | Goal | Guidance | Enforcement |
 | :--- | :--- | :--- | :--- |
@@ -99,6 +287,8 @@ const instructionsBlock = stringifyOutputFormatSpec(spec);
 | **L2** | Fenced Container | "Return inside a single block..." | Exactly one fenced block. |
 | **L3** | Typed Structure | "Reasoning is an ordered list..." | Enforce list/table kinds. |
 
+*Note: These are different from Compliance Levels (which measure spec quality) - Strictness Levels control how strictly Flex-MD enforces the contract on LLM output.*
+
 ## The Repair Pipeline
 
 Flex-MD doesn't just validate; it **repairs**. Our deterministic 9-step plan handles:
@@ -108,12 +298,206 @@ Flex-MD doesn't just validate; it **repairs**. Our deterministic 9-step plan han
 4. **Stray Content**: Moving text outside headings into a default section.
 5. **Format Conversion**: Transforming bullets to numbered lists (and vice-versa) based on spec.
 
+## Real-World Example
+
+```typescript
+import { 
+  parseOutputFormatSpec, 
+  getMaxTokens, 
+  analyzeSpec,
+  enforceFlexMd 
+} from 'flex-md';
+
+// 1. Define spec with system parts
+const spec = parseOutputFormatSpec(`
+## Output format
+- Executive Summary — text (required)
+  Length: 2-3 paragraphs. Summarize findings and recommendations.
+
+- Key Metrics — table (required)
+  Rows: 5-7, Columns: 3. Include: Metric, Current, Target.
+
+- Action Items — ordered list (required)
+  Items: 5-10. Prioritize by impact.
+
+- Technical Details — code (optional)
+  Lines: 20-30. Include implementation examples.
+`);
+
+// 2. Analyze spec quality
+const analysis = analyzeSpec(spec, 2);
+console.log(`Confidence: ${analysis.confidence.grade}`);
+console.log(`Max tokens: ${analysis.tokenEstimate.total.estimated}`);
+
+// 3. Use in API call
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: getMaxTokens(spec, { safetyMultiplier: 1.3 }),
+  messages: [{
+    role: 'user',
+    content: `Analyze Q4 performance.\n\n${buildMarkdownGuidance(spec)}`
+  }]
+});
+
+// 4. Enforce and extract
+const result = enforceFlexMd(response.content[0].text, spec, { level: 2 });
+
+if (result.ok) {
+  const summary = result.extracted.sectionsByName["Executive Summary"].md;
+  const metrics = result.extracted.sectionsByName["Key Metrics"].md;
+  // Use structured output...
+}
+```
+
+## Advanced Usage
+
+### Custom Token Estimation
+
+```typescript
+const estimate = estimateSpecTokens(spec, {
+  includeOptional: false,      // Skip optional sections
+  safetyMultiplier: 1.5,       // Extra headroom
+  strategy: 'conservative'     // Use minimum estimates
+});
+```
+
+### CI/CD Integration
+
+```typescript
+// validate-specs.ts
+import { analyzeSpec } from 'flex-md';
+
+const analysis = analyzeSpec(spec, 2);
+
+const highPriorityIssues = analysis.recommendations
+  .filter(r => r.priority === 'high');
+
+if (highPriorityIssues.length > 0) {
+  console.error('High priority issues found');
+  process.exit(1);
+}
+```
+
+### Progressive Enhancement
+
+Start simple and upgrade as needed:
+
+```typescript
+// Version 1: No system parts (works, but fallback estimation)
+const v1 = `
+## Output format
+- Summary — text (required)
+  Write a summary.
+`;
+
+// Version 2: Add L1 system parts (better)
+const v2 = `
+## Output format
+- Summary — text (required)
+  Length: brief. Write a summary.
+`;
+
+// Version 3: Upgrade to L2 (best balance)
+const v3 = `
+## Output format
+- Summary — text (required)
+  Length: 2-3 sentences. Write a summary.
+`;
+```
+
+## API Reference
+
+### Core Functions
+- `parseOutputFormatSpec(markdown)` - Parse spec from markdown
+- `stringifyOutputFormatSpec(spec)` - Convert spec to markdown
+- `buildMarkdownGuidance(spec, options)` - Generate LLM instructions
+- `enforceFlexMd(text, spec, options)` - Validate and repair LLM output
+
+### Token Estimation (v4.0)
+- `getMaxTokens(spec, options?)` - Get estimated max_tokens
+- `estimateSpecTokens(spec, options?)` - Detailed token estimate
+- `parseSystemPart(instruction, kind)` - Parse system part from instruction
+- `estimateTokens(systemPart)` - Estimate tokens for system part
+
+### Smart Toolbox (v4.0)
+- `checkCompliance(spec, level)` - Validate compliance level
+- `calculateConfidence(spec)` - Score estimation confidence
+- `calculateCognitiveCost(spec)` - Measure spec complexity
+- `detectImprovements(spec, level?)` - Find issues and suggestions
+- `autoFix(spec, improvements, options?)` - Apply automatic fixes
+- `analyzeSpec(spec, level?)` - Complete smart analysis
+
+### Reporting (v4.0)
+- `formatComplianceReport(report)` - Format compliance check
+- `formatImprovementReport(analysis)` - Format improvements
+- `formatSmartReport(analysis)` - Format complete analysis
+
 ## Documentation
 
-Detailed guides and specs can be found in the [docs](./docs) folder:
-- [MDFlex Compliance Spec](./docs/mdflex-compliance.md)
-- [OFS Syntax Guide](./SPEC.md)
+Detailed guides can be found in the [docs](./docs) folder:
+- [System Parts Guide](./docs/system-parts.md) - Complete protocol reference
+- [Token Estimation Guide](./docs/token-estimation.md) - How estimation works
+- [Smart Toolbox Guide](./docs/smart-toolbox.md) - Using analysis features
+- [MDFlex Compliance Spec](./docs/mdflex-compliance.md) - Output enforcement
+- [OFS Syntax Guide](./SPEC.md) - Output Format Spec syntax
+
+## Migration from v3.0
+
+v4.0 is **100% backwards compatible** with v3.0. All existing code continues to work.
+
+To adopt v4.0 features:
+
+1. **Add system parts** to your spec instructions:
+   ```diff
+   - Summary — text (required)
+   -   Provide a brief overview.
+   + Summary — text (required)
+   +   Length: 2-3 sentences. Provide a brief overview.
+   ```
+
+2. **Use token estimation**:
+   ```typescript
+   const maxTokens = getMaxTokens(spec);
+   ```
+
+3. **Analyze and improve** your specs:
+   ```typescript
+   const analysis = analyzeSpec(spec);
+   console.log(formatSmartReport(analysis));
+   ```
+
+## Why Flex-MD v4.0?
+
+### Before v4.0
+```typescript
+// Guessing max_tokens
+const response = await api.create({
+  max_tokens: 2000,  // 🤷 Is this enough? Too much?
+  ...
+});
+```
+
+### After v4.0
+```typescript
+// Precise estimation
+const maxTokens = getMaxTokens(spec);  // ✓ 650 tokens (±20%)
+const response = await api.create({
+  max_tokens,  // 🎯 Right-sized
+  ...
+});
+```
+
+### Benefits
+- ⚡ **Faster responses**: Right-sized tokens mean lower latency
+- 💰 **Lower costs**: Don't overpay for unused tokens
+- 🎯 **Better accuracy**: Clear size expectations guide LLMs
+- 🔍 **Quality insights**: Know your spec's strengths/weaknesses
+- 🛠️ **Easy maintenance**: Auto-detect and fix issues
 
 ## License
 
 MIT
+
+---
+
+**Flex-MD v4.0** - Smart Markdown contracts for production LLM applications.

package/dist/index.cjs

@@ -1,3 +1,62 @@
-// Auto-generated CJS bridge for flex-md
-const m = await import('./index.js');
-module.exports = m;
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.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.validateFormat = exports.parseOutputFormatSpec = exports.buildOutline = void 0;
+// Core SFMD Types
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./strictness/types.js"), exports);
+// Shared MD Parsing
+__exportStar(require("./md/parse.js"), exports);
+var outline_js_1 = require("./md/outline.js");
+Object.defineProperty(exports, "buildOutline", { enumerable: true, get: function () { return outline_js_1.buildOutline; } });
+// Output Format Spec (OFS)
+var parser_js_1 = require("./ofs/parser.js");
+Object.defineProperty(exports, "parseOutputFormatSpec", { enumerable: true, get: function () { return parser_js_1.parseOutputFormatSpec; } });
+Object.defineProperty(exports, "validateFormat", { enumerable: true, get: function () { return parser_js_1.validateFormat; } });
+var stringify_js_1 = require("./ofs/stringify.js");
+Object.defineProperty(exports, "stringifyOutputFormatSpec", { enumerable: true, get: function () { return stringify_js_1.stringifyOutputFormatSpec; } });
+var enricher_js_1 = require("./ofs/enricher.js");
+Object.defineProperty(exports, "buildMarkdownGuidance", { enumerable: true, get: function () { return enricher_js_1.buildMarkdownGuidance; } });
+Object.defineProperty(exports, "enrichInstructions", { enumerable: true, get: function () { return enricher_js_1.enrichInstructions; } });
+Object.defineProperty(exports, "enrichInstructionsWithFlexMd", { enumerable: true, get: function () { return enricher_js_1.enrichInstructionsWithFlexMd; } });
+// Validation & Extraction
+var validate_js_1 = require("./validate/validate.js");
+Object.defineProperty(exports, "validateMarkdownAgainstOfs", { enumerable: true, get: function () { return validate_js_1.validateMarkdownAgainstOfs; } });
+var compliance_js_1 = require("./validate/compliance.js");
+Object.defineProperty(exports, "checkCompliance", { enumerable: true, get: function () { return compliance_js_1.checkCompliance; } });
+Object.defineProperty(exports, "hasFlexMdContract", { enumerable: true, get: function () { return compliance_js_1.hasFlexMdContract; } });
+var connection_js_1 = require("./validate/connection.js");
+Object.defineProperty(exports, "checkConnection", { enumerable: true, get: function () { return connection_js_1.checkConnection; } });
+var extract_js_1 = require("./extract/extract.js");
+Object.defineProperty(exports, "extractFromMarkdown", { enumerable: true, get: function () { return extract_js_1.extractFromMarkdown; } });
+// Processor & Fallback
+var processor_js_1 = require("./strictness/processor.js");
+Object.defineProperty(exports, "processResponseMarkdown", { enumerable: true, get: function () { return processor_js_1.processResponseMarkdown; } });
+var issuesEnvelope_js_1 = require("./ofs/issuesEnvelope.js");
+Object.defineProperty(exports, "parseIssuesEnvelope", { enumerable: true, get: function () { return issuesEnvelope_js_1.parseIssuesEnvelope; } });
+Object.defineProperty(exports, "buildIssuesEnvelope", { enumerable: true, get: function () { return issuesEnvelope_js_1.buildIssuesEnvelope; } });
+Object.defineProperty(exports, "buildIssuesEnvelopeAuto", { enumerable: true, get: function () { return issuesEnvelope_js_1.buildIssuesEnvelopeAuto; } });
+// Pipeline
+var kind_js_1 = require("./pipeline/kind.js");
+Object.defineProperty(exports, "detectResponseKind", { enumerable: true, get: function () { return kind_js_1.detectResponseKind; } });
+var repair_js_1 = require("./pipeline/repair.js");
+Object.defineProperty(exports, "repairToMarkdownLevel", { enumerable: true, get: function () { return repair_js_1.repairToMarkdownLevel; } });
+var enforce_js_1 = require("./pipeline/enforce.js");
+Object.defineProperty(exports, "enforceFlexMd", { enumerable: true, get: function () { return enforce_js_1.enforceFlexMd; } });
+// JSON Detection
+__exportStar(require("./detect/json/index.js"), exports);
+// Token Estimation
+__exportStar(require("./tokens/index.js"), exports);

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export { detectResponseKind } from "./pipeline/kind.js";
 export { repairToMarkdownLevel } from "./pipeline/repair.js";
 export { enforceFlexMd } from "./pipeline/enforce.js";
 export * from "./detect/json/index.js";
+export * from "./tokens/index.js";

package/dist/index.js

@@ -22,3 +22,5 @@ export { repairToMarkdownLevel } from "./pipeline/repair.js";
 export { enforceFlexMd } from "./pipeline/enforce.js";
 // JSON Detection
 export * from "./detect/json/index.js";
+// Token Estimation
+export * from "./tokens/index.js";

package/dist/md/parse.d.ts

@@ -27,3 +27,4 @@ export interface ParsedSection {
 export declare function parseHeadingsAndSections(md: string): ParsedSection[];
 export declare function extractBullets(body: string): string[];
 export declare function isIssuesEnvelopeCheck(md: string): IssuesEnvelope;
+export declare function markdownToJson(md: string): Record<string, any>;

package/dist/md/parse.js

@@ -1,3 +1,4 @@
+import { toCamelCase } from "nx-helpers";
 export function normalizeName(s) {
     return s.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -114,3 +115,14 @@ export function isIssuesEnvelopeCheck(md) {
     }
     return { isIssuesEnvelope: ok, sections };
 }
+export function markdownToJson(md) {
+    // Robustly handle both actual newlines and literal \n (common in LLM JSON outputs)
+    const normalizedMd = (md || "").replace(/\\n/g, "\n");
+    const sections = parseHeadingsAndSections(normalizedMd);
+    const result = {};
+    for (const sec of sections) {
+        const key = toCamelCase(sec.heading.name);
+        result[key] = sec.body.trim();
+    }
+    return result;
+}