flex-md 3.5.0 → 4.0.0

package/dist/ofs/parser.js

@@ -96,36 +96,53 @@ export function parseOutputFormatSpec(md, opts = {}) {
     const tables = [];
     let emptySectionValue;
     let inTables = false;
+    let currentSection = null;
     for (const rawLine of block.split("\n")) {
         const line = rawLine.trim();
         if (/^tables\b/i.test(line)) {
             inTables = true;
+            currentSection = null;
             continue;
         }
         if (/^empty sections\b/i.test(line)) {
             inTables = false;
+            currentSection = null;
             continue;
         }
         // Empty section rule
         const mNone = line.match(/write\s+`([^`]+)`/i);
         if (/empty/i.test(line) && mNone) {
             emptySectionValue = mNone[1];
+            currentSection = null;
             continue;
         }
         // bullet items
         const bullet = line.match(/^- (.+)$/);
-        if (!bullet)
-            continue;
-        const item = bullet[1];
-        if (inTables) {
-            const t = parseTableDecl(item);
-            if (t)
-                tables.push(t);
+        if (bullet) {
+            const item = bullet[1];
+            if (inTables) {
+                const t = parseTableDecl(item);
+                if (t)
+                    tables.push(t);
+                currentSection = null;
+            }
+            else {
+                const s = parseSectionDecl(item, !!opts.allowDelimiterFallbacks);
+                if (s) {
+                    sections.push(s);
+                    currentSection = s;
+                }
+                else {
+                    currentSection = null;
+                }
+            }
             continue;
         }
-        const s = parseSectionDecl(item, !!opts.allowDelimiterFallbacks);
-        if (s)
-            sections.push(s);
+        // If not a bullet and we have a current section, it's an instruction
+        if (currentSection && line.length > 0) {
+            const existing = currentSection.instruction || "";
+            currentSection.instruction = existing ? `${existing} ${line}` : line;
+        }
     }
     if (!sections.length)
         return null;
@@ -169,6 +186,10 @@ function normalizeSectionKind(rest) {
         return "list";
     if (r.includes("prose") || r.includes("text"))
         return "text";
+    if (r.includes("ordered") && r.includes("table"))
+        return "ordered_table";
+    if (r.includes("table"))
+        return "table";
     return null;
 }
 function parseTableDecl(item) {

package/dist/tokens/auto-fix.d.ts

@@ -0,0 +1,10 @@
+import type { AutoFixResult, Improvement } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+/**
+ * Automatically apply fixable improvements
+ */
+export declare function autoFix(spec: OutputFormatSpec, improvements: Improvement[], options?: {
+    applyQuickWinsOnly?: boolean;
+    maxPriority?: Improvement['priority'];
+    skipManual?: boolean;
+}): AutoFixResult;

package/dist/tokens/auto-fix.js

@@ -0,0 +1,56 @@
+/**
+ * Automatically apply fixable improvements
+ */
+export function autoFix(spec, improvements, options = {}) {
+    const { applyQuickWinsOnly = false, maxPriority = 'low', skipManual = true } = options;
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    const maxPriorityLevel = priorityOrder[maxPriority] ?? 3;
+    const appliedFixes = [];
+    const skippedFixes = [];
+    const fixedSections = spec.sections.map(section => {
+        const sectionImprovements = improvements.filter(imp => imp.sectionName === section.name);
+        let currentInstruction = section.instruction;
+        let modified = false;
+        // Sort improvements by priority for this section
+        const sortedImps = [...sectionImprovements].sort((a, b) => (priorityOrder[a.priority] ?? 3) - (priorityOrder[b.priority] ?? 3));
+        for (const improvement of sortedImps) {
+            // Check if should apply
+            if ((priorityOrder[improvement.priority] ?? 3) > maxPriorityLevel)
+                continue;
+            if (applyQuickWinsOnly && improvement.effort !== 'trivial' && improvement.effort !== 'easy')
+                continue;
+            if (!improvement.autoFixable) {
+                skippedFixes.push({
+                    sectionName: section.name,
+                    reason: 'Requires manual review',
+                    manualActionNeeded: improvement.suggestion
+                });
+                continue;
+            }
+            // Apply fix (only the first one for simplicity, or could chain)
+            // For now, we chain them by using the 'after' of the previous as 'before' of the next
+            // But 'before' in improvement object is relative to the ORIGINAL state.
+            // So we just apply the one with the highest priority for the section.
+            appliedFixes.push({
+                sectionName: section.name,
+                improvement: improvement.issue,
+                before: currentInstruction || '',
+                after: improvement.after
+            });
+            currentInstruction = improvement.after;
+            modified = true;
+            break; // Only apply one fix per section in this pass to avoid conflicts
+        }
+        return modified ? { ...section, instruction: currentInstruction } : section;
+    });
+    const summary = `Applied ${appliedFixes.length} fixes, skipped ${skippedFixes.length}`;
+    return {
+        fixed: {
+            ...spec,
+            sections: fixedSections
+        },
+        appliedFixes,
+        skippedFixes,
+        summary
+    };
+}

package/dist/tokens/cognitive-cost.d.ts

@@ -0,0 +1,10 @@
+import type { CognitiveCost, LevelCostComparison } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+/**
+ * Calculate cognitive cost of creating/maintaining spec
+ */
+export declare function calculateCognitiveCost(spec: OutputFormatSpec): CognitiveCost;
+/**
+ * Compare cognitive cost across different compliance levels
+ */
+export declare function compareLevelCosts(spec: OutputFormatSpec): LevelCostComparison;

package/dist/tokens/cognitive-cost.js

@@ -0,0 +1,205 @@
+import { parseSystemPart } from './parser.js';
+import { detectSystemPartLevel } from './compliance.js';
+/**
+ * Calculate cognitive cost of creating/maintaining spec
+ */
+export function calculateCognitiveCost(spec) {
+    const perSection = [];
+    let totalCost = 0;
+    let complexityCost = 0;
+    let decisionCost = 0;
+    for (const section of spec.sections) {
+        const sectionCost = calculateSectionCost(section);
+        perSection.push(sectionCost);
+        totalCost += sectionCost.cost;
+        // Track breakdown
+        complexityCost += getComplexityCost(section.kind || 'text');
+        decisionCost += getDecisionCost(sectionCost.level);
+    }
+    const baseCost = spec.sections.length * 1; // Base effort per section
+    return {
+        totalCost: Math.min(100, totalCost),
+        perSection,
+        breakdown: {
+            baseCost,
+            complexityCost,
+            decisionCost,
+            totalSections: spec.sections.length
+        },
+        recommendation: generateCostRecommendation(totalCost, spec.sections.length)
+    };
+}
+/**
+ * Calculate cost for individual section
+ */
+function calculateSectionCost(section) {
+    const kind = section.kind || 'text';
+    const systemPart = parseSystemPart(section.instruction, kind);
+    const level = systemPart ? detectSystemPartLevel(systemPart, kind) : null;
+    const factors = [];
+    let cost = 0;
+    // Base cost by level
+    const levelCosts = { 0: 0, 1: 1, 2: 3, 3: 5 };
+    const levelCost = levelCosts[level || 0];
+    cost += levelCost;
+    if (level !== null && level > 0) {
+        factors.push({
+            factor: 'system_part_level',
+            impact: levelCost,
+            description: `L${level} requires ${getLevelEffortDescription(level)}`
+        });
+    }
+    // Complexity by section kind
+    const kindCost = getComplexityCost(kind);
+    cost += kindCost;
+    if (kindCost > 0) {
+        factors.push({
+            factor: 'section_complexity',
+            impact: kindCost,
+            description: getKindComplexityDescription(kind)
+        });
+    }
+    // Additional cost for specific patterns
+    if (systemPart) {
+        const patternCost = getPatternCost(systemPart);
+        cost += patternCost.cost;
+        if (patternCost.cost > 0) {
+            factors.push({
+                factor: 'pattern_complexity',
+                impact: patternCost.cost,
+                description: patternCost.description
+            });
+        }
+    }
+    return {
+        sectionName: section.name,
+        cost,
+        level,
+        factors
+    };
+}
+function getLevelEffortDescription(level) {
+    const descriptions = {
+        0: 'no thinking',
+        1: 'picking from 4 simple options',
+        2: 'thinking about ranges',
+        3: 'considering minimums and approximations'
+    };
+    return descriptions[level];
+}
+function getComplexityCost(kind) {
+    const costs = {
+        'text': 0, // Simplest
+        'list': 1,
+        'ordered_list': 1,
+        'code': 1,
+        'table': 2, // Most complex (2 dimensions)
+        'ordered_table': 2
+    };
+    return costs[kind] || 0;
+}
+function getKindComplexityDescription(kind) {
+    const descriptions = {
+        'text': 'Simple single value',
+        'list': 'Need to estimate item count',
+        'ordered_list': 'Need to estimate item count',
+        'code': 'Need to estimate line count',
+        'table': 'Need to think about rows AND columns',
+        'ordered_table': 'Need to think about rows AND columns'
+    };
+    return descriptions[kind] || '';
+}
+function getDecisionCost(level) {
+    if (level === null)
+        return 0;
+    const costs = { 0: 0, 1: 0.5, 2: 1.5, 3: 2.5 };
+    return costs[level];
+}
+function getPatternCost(systemPart) {
+    const { parsed } = systemPart;
+    switch (parsed.type) {
+        case 'items':
+        case 'lines':
+            if (parsed.atLeast) {
+                return { cost: 1, description: 'Deciding "at least" minimum requires judgment' };
+            }
+            if (parsed.max !== null) {
+                return { cost: 0.5, description: 'Ranges require estimating both min and max' };
+            }
+            return { cost: 0, description: '' };
+        case 'table':
+            let tableCost = 0;
+            let desc = [];
+            if (parsed.rows.atLeast || parsed.columns.atLeast) {
+                tableCost += 1;
+                desc.push('minimums require judgment');
+            }
+            if (parsed.rows.max !== null || parsed.columns.max !== null) {
+                tableCost += 0.5;
+                desc.push('ranges require estimation');
+            }
+            return {
+                cost: tableCost,
+                description: desc.length > 0 ? `Two dimensions: ${desc.join(', ')}` : ''
+            };
+        default:
+            return { cost: 0, description: '' };
+    }
+}
+function generateCostRecommendation(totalCost, sectionCount) {
+    if (sectionCount === 0)
+        return 'Empty spec';
+    const avgCost = totalCost / sectionCount;
+    if (avgCost < 2) {
+        return 'Low cognitive load - easy to write and maintain';
+    }
+    else if (avgCost < 4) {
+        return 'Moderate cognitive load - reasonable effort required';
+    }
+    else if (avgCost < 6) {
+        return 'High cognitive load - consider simplifying some sections';
+    }
+    else {
+        return 'Very high cognitive load - strongly consider reducing to L2 or L1 for some sections';
+    }
+}
+/**
+ * Compare cognitive cost across different compliance levels
+ */
+export function compareLevelCosts(spec) {
+    const costs = { 0: 0, 1: 0, 2: 0, 3: 0 };
+    // Simulate cost at each level
+    for (let level = 0; level <= 3; level++) {
+        costs[level] = estimateCostAtLevel(spec, level);
+    }
+    return {
+        byLevel: costs,
+        recommendation: getBestLevelForCost(costs)
+    };
+}
+function estimateCostAtLevel(spec, level) {
+    const levelBaseCosts = { 0: 0, 1: 1, 2: 3, 3: 5 };
+    const baseCost = levelBaseCosts[level];
+    let total = spec.sections.length * baseCost;
+    // Add complexity cost
+    for (const section of spec.sections) {
+        total += getComplexityCost(section.kind || 'text');
+        total += getDecisionCost(level);
+    }
+    return total;
+}
+function getBestLevelForCost(costs) {
+    // L2 is usually the sweet spot
+    if (costs[2] < 50) {
+        return 'L2 recommended - good balance of precision and effort';
+    }
+    else if (costs[1] < 30) {
+        return 'L1 recommended - keep it simple for this spec';
+    }
+    else if (costs[3] < 70) {
+        return 'L3 acceptable - complexity is manageable';
+    }
+    else {
+        return 'Consider reducing spec size or using L1/L2';
+    }
+}

package/dist/tokens/compliance.d.ts

@@ -0,0 +1,10 @@
+import type { ComplianceLevel, ComplianceReport, SystemPart } from './types.js';
+import type { OutputFormatSpec, SectionKind } from '../types.js';
+/**
+ * Detect the compliance level of a system part
+ */
+export declare function detectSystemPartLevel(systemPart: SystemPart, kind: SectionKind | 'code'): ComplianceLevel;
+/**
+ * Check if a spec complies with a target level
+ */
+export declare function checkSpecCompliance(spec: OutputFormatSpec, targetLevel?: ComplianceLevel): ComplianceReport;

package/dist/tokens/compliance.js

@@ -0,0 +1,70 @@
+import { parseSystemPart } from './parser.js';
+/**
+ * Detect the compliance level of a system part
+ */
+export function detectSystemPartLevel(systemPart, kind) {
+    const { parsed } = systemPart;
+    switch (parsed.type) {
+        case 'length':
+            // Ranges in lengths are L2
+            if (['1-2 sentences', '2-3 paragraphs'].includes(parsed.value)) {
+                return 2;
+            }
+            return 1;
+        case 'items':
+        case 'lines':
+            if (parsed.atLeast || parsed.approximate)
+                return 3;
+            if (parsed.max !== null)
+                return 2;
+            return 1;
+        case 'table':
+            if (parsed.rows.atLeast || parsed.columns.atLeast)
+                return 3;
+            if (parsed.rows.max !== null || parsed.columns.max !== null)
+                return 2;
+            return 1;
+        default:
+            return 0;
+    }
+}
+/**
+ * Check if a spec complies with a target level
+ */
+export function checkSpecCompliance(spec, targetLevel = 2) {
+    const violations = [];
+    let totalLevel = 0;
+    let compliantCount = 0;
+    for (const section of spec.sections) {
+        const kind = section.kind || 'text';
+        const systemPart = parseSystemPart(section.instruction, kind);
+        const level = systemPart ? detectSystemPartLevel(systemPart, kind) : 0;
+        totalLevel += level;
+        if (level >= targetLevel) {
+            compliantCount++;
+        }
+        else if (section.required !== false) {
+            violations.push({
+                sectionName: section.name,
+                kind,
+                level,
+                message: `Section '${section.name}' is at L${level}, but target is L${targetLevel}`
+            });
+        }
+        else {
+            // Optional sections don't cause violations but we still count them if they are compliant
+            if (level >= targetLevel)
+                compliantCount++;
+        }
+    }
+    return {
+        compliant: violations.length === 0,
+        level: targetLevel,
+        violations,
+        summary: {
+            totalSections: spec.sections.length,
+            compliantSections: compliantCount,
+            averageLevel: spec.sections.length > 0 ? totalLevel / spec.sections.length : 0
+        }
+    };
+}

package/dist/tokens/confidence.d.ts

@@ -0,0 +1,6 @@
+import type { ConfidenceScore } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+/**
+ * Calculate confidence in token estimation
+ */
+export declare function calculateConfidence(spec: OutputFormatSpec): ConfidenceScore;