flex-md 3.5.0 → 4.0.0

package/dist/tokens/confidence.js

@@ -0,0 +1,332 @@
+import { parseSystemPart } from './parser.js';
+import { detectSystemPartLevel } from './compliance.js';
+/**
+ * Calculate confidence in token estimation
+ */
+export function calculateConfidence(spec) {
+    const bySection = [];
+    const factors = [];
+    let totalConfidence = 0;
+    let totalWeight = 0;
+    // Analyze each section
+    for (const section of spec.sections) {
+        const sectionConf = analyzeSectionConfidence(section);
+        bySection.push(sectionConf);
+        // Weight required sections more heavily
+        const weight = section.required !== false ? 2 : 1;
+        totalConfidence += sectionConf.confidence * weight;
+        totalWeight += weight;
+    }
+    // Calculate coverage factor
+    const coverageFactor = calculateCoverageFactor(spec);
+    factors.push(coverageFactor);
+    // Calculate specificity factor
+    const specificityFactor = calculateSpecificityFactor(bySection);
+    factors.push(specificityFactor);
+    // Calculate consistency factor
+    const consistencyFactor = calculateConsistencyFactor(bySection);
+    factors.push(consistencyFactor);
+    // Calculate required coverage factor
+    const requiredFactor = calculateRequiredCoverageFactor(spec, bySection);
+    factors.push(requiredFactor);
+    // Combine all factors
+    let overall = totalWeight > 0 ? totalConfidence / totalWeight : 0;
+    // Apply factor adjustments
+    for (const factor of factors) {
+        overall += factor.score;
+    }
+    overall = Math.max(0, Math.min(100, overall));
+    return {
+        overall,
+        grade: getConfidenceGrade(overall),
+        bySection,
+        factors,
+        recommendations: generateConfidenceRecommendations(overall, factors, bySection)
+    };
+}
+/**
+ * Analyze confidence for individual section
+ */
+function analyzeSectionConfidence(section) {
+    const kind = section.kind || 'text';
+    const systemPart = parseSystemPart(section.instruction, kind);
+    const hasSystemPart = systemPart !== null;
+    const level = systemPart ? detectSystemPartLevel(systemPart, kind) : null;
+    let confidence = 0;
+    let quality = 'none';
+    if (systemPart && level !== null) {
+        // Base confidence from level
+        const levelConfidence = { 0: 0, 1: 60, 2: 80, 3: 90 };
+        confidence = levelConfidence[level] || 0;
+        // Adjust based on section characteristics
+        const adjustment = getConfidenceAdjustment(systemPart, section);
+        confidence += adjustment;
+        confidence = Math.max(0, Math.min(100, confidence));
+        // Determine quality
+        if (confidence >= 85)
+            quality = 'excellent';
+        else if (confidence >= 70)
+            quality = 'good';
+        else if (confidence >= 50)
+            quality = 'fair';
+        else
+            quality = 'poor';
+    }
+    return {
+        sectionName: section.name,
+        confidence,
+        hasSystemPart,
+        level,
+        estimateQuality: quality
+    };
+}
+function getConfidenceAdjustment(systemPart, _section) {
+    let adjustment = 0;
+    const { parsed } = systemPart;
+    switch (parsed.type) {
+        case 'length':
+            // Specific values are better than vague ones
+            if (['1 sentence', '1-2 sentences', '1 paragraph', '2-3 paragraphs'].includes(parsed.value)) {
+                adjustment += 10; // Concrete measurements
+            }
+            break;
+        case 'items':
+            // Exact numbers or tight ranges are better
+            if (parsed.max !== null) {
+                const range = parsed.max - parsed.min;
+                if (range <= 2)
+                    adjustment += 10; // Tight range
+                else if (range <= 5)
+                    adjustment += 5; // Reasonable range
+            }
+            else if (!parsed.atLeast) {
+                adjustment += 10; // Exact number
+            }
+            break;
+        case 'table':
+            // Both dimensions specified tightly
+            const rowsExact = parsed.rows.max === null && !parsed.rows.atLeast;
+            const colsExact = parsed.columns.max === null && !parsed.columns.atLeast;
+            if (rowsExact && colsExact) {
+                adjustment += 10; // Both exact
+            }
+            else if (rowsExact || colsExact) {
+                adjustment += 5; // One exact
+            }
+            break;
+        case 'lines':
+            // Non-approximate is better
+            if (!parsed.approximate) {
+                adjustment += 5;
+            }
+            if (parsed.max !== null) {
+                const range = parsed.max - parsed.min;
+                if (range <= 10)
+                    adjustment += 5; // Tight range
+            }
+            break;
+    }
+    // Penalty for very vague patterns
+    if (parsed.type === 'items' && parsed.atLeast && parsed.min < 3) {
+        adjustment -= 10; // "at least 1" is very vague
+    }
+    return adjustment;
+}
+/**
+ * Calculate coverage factor (what % of sections have system parts)
+ */
+function calculateCoverageFactor(spec) {
+    const total = spec.sections.length;
+    const withSystemParts = spec.sections.filter(s => parseSystemPart(s.instruction, s.kind || 'text') !== null).length;
+    const coverage = total > 0 ? (withSystemParts / total) * 100 : 0;
+    let score = 0;
+    let impact = 'neutral';
+    if (coverage >= 90) {
+        score = 10;
+        impact = 'positive';
+    }
+    else if (coverage >= 70) {
+        score = 5;
+        impact = 'positive';
+    }
+    else if (coverage < 50) {
+        score = -10;
+        impact = 'negative';
+    }
+    else {
+        score = -5;
+        impact = 'negative';
+    }
+    return {
+        factor: 'coverage',
+        impact,
+        score,
+        description: `${coverage.toFixed(0)}% of sections have system parts`
+    };
+}
+/**
+ * Calculate specificity factor (are system parts specific or vague?)
+ */
+function calculateSpecificityFactor(sections) {
+    const withSystemParts = sections.filter(s => s.hasSystemPart);
+    if (withSystemParts.length === 0) {
+        return {
+            factor: 'specificity',
+            impact: 'negative',
+            score: -15,
+            description: 'No system parts to evaluate'
+        };
+    }
+    const avgLevel = withSystemParts.reduce((sum, s) => sum + (s.level || 0), 0) / withSystemParts.length;
+    let score = 0;
+    let impact = 'neutral';
+    if (avgLevel >= 2.5) {
+        score = 10;
+        impact = 'positive';
+    }
+    else if (avgLevel >= 2) {
+        score = 5;
+        impact = 'positive';
+    }
+    else if (avgLevel < 1.5) {
+        score = -5;
+        impact = 'negative';
+    }
+    return {
+        factor: 'specificity',
+        impact,
+        score,
+        description: `Average specificity level: L${avgLevel.toFixed(1)}`
+    };
+}
+/**
+ * Calculate consistency factor (are all sections at similar level?)
+ */
+function calculateConsistencyFactor(sections) {
+    const levels = sections
+        .filter(s => s.level !== null)
+        .map(s => s.level);
+    if (levels.length === 0) {
+        return {
+            factor: 'consistency',
+            impact: 'neutral',
+            score: 0,
+            description: 'No levels to compare'
+        };
+    }
+    const min = Math.min(...levels);
+    const max = Math.max(...levels);
+    const variance = max - min;
+    let score = 0;
+    let impact = 'neutral';
+    if (variance === 0) {
+        score = 5;
+        impact = 'positive';
+    }
+    else if (variance >= 3) {
+        score = -5;
+        impact = 'negative';
+    }
+    return {
+        factor: 'consistency',
+        impact,
+        score,
+        description: variance === 0
+            ? 'All sections at same level (consistent)'
+            : `Level variance: ${variance} (${min} to ${max})`
+    };
+}
+/**
+ * Calculate required coverage (do all required sections have good system parts?)
+ */
+function calculateRequiredCoverageFactor(spec, sections) {
+    const requiredSections = spec.sections.filter(s => s.required !== false);
+    if (requiredSections.length === 0) {
+        return {
+            factor: 'required_coverage',
+            impact: 'neutral',
+            score: 0,
+            description: 'No required sections'
+        };
+    }
+    const requiredWithSystemParts = sections.filter(s => {
+        const section = spec.sections.find(sec => sec.name === s.sectionName);
+        return section?.required !== false && s.hasSystemPart;
+    }).length;
+    const coverage = (requiredWithSystemParts / requiredSections.length) * 100;
+    let score = 0;
+    let impact = 'neutral';
+    if (coverage === 100) {
+        score = 15;
+        impact = 'positive';
+    }
+    else if (coverage >= 80) {
+        score = 5;
+        impact = 'positive';
+    }
+    else if (coverage < 50) {
+        score = -15;
+        impact = 'negative';
+    }
+    else {
+        score = -5;
+        impact = 'negative';
+    }
+    return {
+        factor: 'required_coverage',
+        impact,
+        score,
+        description: `${coverage.toFixed(0)}% of required sections have system parts`
+    };
+}
+function getConfidenceGrade(score) {
+    if (score >= 90)
+        return 'A';
+    if (score >= 80)
+        return 'B';
+    if (score >= 70)
+        return 'C';
+    if (score >= 60)
+        return 'D';
+    return 'F';
+}
+function generateConfidenceRecommendations(overall, factors, sections) {
+    const recommendations = [];
+    // Overall quality
+    if (overall < 70) {
+        recommendations.push('Overall confidence is low. Consider adding more specific system parts.');
+    }
+    // Check negative factors
+    for (const factor of factors) {
+        if (factor.impact === 'negative') {
+            switch (factor.factor) {
+                case 'coverage':
+                    recommendations.push('Add system parts to more sections to improve coverage.');
+                    break;
+                case 'specificity':
+                    recommendations.push('Upgrade some L1 system parts to L2 for better precision.');
+                    break;
+                case 'consistency':
+                    recommendations.push('Consider standardizing compliance level across sections.');
+                    break;
+                case 'required_coverage':
+                    recommendations.push('Ensure all required sections have system parts.');
+                    break;
+            }
+        }
+    }
+    // Check poor quality sections
+    const poorSections = sections.filter(s => s.estimateQuality === 'poor' || s.estimateQuality === 'none');
+    if (poorSections.length > 0) {
+        const names = poorSections.map(s => s.sectionName).join(', ');
+        recommendations.push(`Improve system parts for: ${names}`);
+    }
+    // Positive feedback
+    if (overall >= 90) {
+        recommendations.push('Excellent! Token estimation will be highly accurate.');
+    }
+    else if (overall >= 80) {
+        recommendations.push('Good confidence. Minor improvements possible.');
+    }
+    return recommendations;
+}

package/dist/tokens/estimator.d.ts

@@ -0,0 +1,12 @@
+import type { SystemPart, TokenEstimate, LengthValue } from './types.js';
+import type { SectionKind } from '../types.js';
+export declare const TOKEN_CONSTANTS: {
+    readonly lengths: Record<LengthValue, number>;
+    readonly perItem: 40;
+    readonly perTableCell: 20;
+    readonly perCodeLine: 5;
+    readonly headingOverhead: 10;
+    readonly baseOverhead: 50;
+};
+export declare function estimateTokens(systemPart: SystemPart): TokenEstimate;
+export declare function getFallbackEstimate(kind: SectionKind, required: boolean): TokenEstimate;

package/dist/tokens/estimator.js

@@ -0,0 +1,138 @@
+// Calibrated token constants
+export const TOKEN_CONSTANTS = {
+    // Text lengths (enumerated)
+    lengths: {
+        '1 sentence': 25,
+        '1-2 sentences': 40,
+        '1 paragraph': 100,
+        '2-3 paragraphs': 250,
+        'brief': 75,
+        'moderate': 150,
+        'detailed': 300,
+        'extensive': 500
+    },
+    // Per-unit estimates
+    perItem: 40,
+    perTableCell: 20,
+    perCodeLine: 5,
+    // Overhead
+    headingOverhead: 10,
+    baseOverhead: 50
+};
+export function estimateTokens(systemPart) {
+    const { parsed } = systemPart;
+    switch (parsed.type) {
+        case 'length':
+            return estimateTextLength(parsed.value);
+        case 'items':
+            return estimateItems(parsed);
+        case 'table':
+            return estimateTable(parsed);
+        case 'lines':
+            return estimateCodeLines(parsed);
+    }
+}
+function estimateTextLength(value) {
+    const estimated = TOKEN_CONSTANTS.lengths[value];
+    return {
+        estimated,
+        min: Math.floor(estimated * 0.7),
+        max: Math.ceil(estimated * 1.3),
+        confidence: 'high'
+    };
+}
+function estimateItems(parsed) {
+    const { min, max, atLeast } = parsed;
+    if (max !== null) {
+        // Range: "3-5" → use average
+        const avg = (min + max) / 2;
+        const estimated = Math.round(avg * TOKEN_CONSTANTS.perItem);
+        return {
+            estimated,
+            min: min * TOKEN_CONSTANTS.perItem,
+            max: max * TOKEN_CONSTANTS.perItem,
+            confidence: 'high'
+        };
+    }
+    if (atLeast) {
+        // "at least 3" → estimate at min + 50%
+        const estimated = Math.round(min * 1.5 * TOKEN_CONSTANTS.perItem);
+        return {
+            estimated,
+            min: min * TOKEN_CONSTANTS.perItem,
+            max: min * 3 * TOKEN_CONSTANTS.perItem,
+            confidence: 'medium'
+        };
+    }
+    // Exact: "3" → use exact value
+    const estimated = min * TOKEN_CONSTANTS.perItem;
+    return {
+        estimated,
+        min: Math.floor(estimated * 0.8),
+        max: Math.ceil(estimated * 1.2),
+        confidence: 'high'
+    };
+}
+function estimateTable(parsed) {
+    const rowAvg = parsed.rows.max
+        ? (parsed.rows.min + parsed.rows.max) / 2
+        : parsed.rows.atLeast
+            ? parsed.rows.min * 1.5
+            : parsed.rows.min;
+    const colAvg = parsed.columns.max
+        ? (parsed.columns.min + parsed.columns.max) / 2
+        : parsed.columns.atLeast
+            ? parsed.columns.min * 1.5
+            : parsed.columns.min;
+    const estimated = Math.round(rowAvg * colAvg * TOKEN_CONSTANTS.perTableCell);
+    const minCells = parsed.rows.min * parsed.columns.min;
+    const maxRows = parsed.rows.max || (parsed.rows.atLeast ? parsed.rows.min * 2 : parsed.rows.min);
+    const maxCols = parsed.columns.max || (parsed.columns.atLeast ? parsed.columns.min * 2 : parsed.columns.min);
+    const maxCells = maxRows * maxCols;
+    return {
+        estimated,
+        min: minCells * TOKEN_CONSTANTS.perTableCell,
+        max: maxCells * TOKEN_CONSTANTS.perTableCell,
+        confidence: (parsed.rows.max && parsed.columns.max) ? 'high' : 'medium'
+    };
+}
+function estimateCodeLines(parsed) {
+    const { min, max, approximate } = parsed;
+    if (max !== null) {
+        // Range: "10-20"
+        const avg = (min + max) / 2;
+        const estimated = Math.round(avg * TOKEN_CONSTANTS.perCodeLine);
+        return {
+            estimated,
+            min: min * TOKEN_CONSTANTS.perCodeLine,
+            max: max * TOKEN_CONSTANTS.perCodeLine,
+            confidence: 'high'
+        };
+    }
+    // Exact or approximate: "10" or "~10"
+    const estimated = min * TOKEN_CONSTANTS.perCodeLine;
+    const variance = approximate ? 0.3 : 0.15;
+    return {
+        estimated,
+        min: Math.floor(estimated * (1 - variance)),
+        max: Math.ceil(estimated * (1 + variance)),
+        confidence: approximate ? 'medium' : 'high'
+    };
+}
+// Fallback for sections without system parts
+export function getFallbackEstimate(kind, required) {
+    const fallbacks = {
+        text: 150,
+        list: 200,
+        'ordered-list': 200,
+        table: 300,
+        code: 400
+    };
+    const base = fallbacks[kind] || 150;
+    return {
+        estimated: base,
+        min: Math.floor(base * 0.5),
+        max: Math.ceil(base * 2),
+        confidence: 'low'
+    };
+}

package/dist/tokens/improvements.d.ts

@@ -0,0 +1,10 @@
+import type { ImprovementAnalysis, ComplianceLevel } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+/**
+ * Main improvement detector
+ */
+export declare function detectImprovements(spec: OutputFormatSpec, targetLevel?: ComplianceLevel): ImprovementAnalysis;
+/**
+ * Format improvement report
+ */
+export declare function formatImprovementReport(analysis: ImprovementAnalysis): string;