flex-md 3.2.0 → 4.0.0

package/dist/tokens/index.d.ts

@@ -0,0 +1,24 @@
+import type { OutputFormatSpec } from '../types.js';
+export * from './types.js';
+export * from './parser.js';
+export * from './estimator.js';
+export * from './spec-estimator.js';
+export * from './validator.js';
+export * from './compliance.js';
+export * from './cognitive-cost.js';
+export * from './confidence.js';
+export * from './smart-report.js';
+export * from './improvements.js';
+export * from './auto-fix.js';
+/**
+ * Convenience function: estimate max_tokens from spec
+ *
+ * @param spec - OutputFormatSpec object or markdown string
+ * @param options - Estimation options
+ * @returns Estimated max_tokens value
+ */
+export declare function getMaxTokens(spec: OutputFormatSpec | string | null | undefined, options?: {
+    includeOptional?: boolean;
+    safetyMultiplier?: number;
+    strategy?: 'conservative' | 'average' | 'generous';
+}): number;

package/dist/tokens/index.js

@@ -0,0 +1,31 @@
+import { parseOutputFormatSpec } from '../ofs/parser.js';
+import { estimateSpecTokens } from './spec-estimator.js';
+export * from './types.js';
+export * from './parser.js';
+export * from './estimator.js';
+export * from './spec-estimator.js';
+export * from './validator.js';
+export * from './compliance.js';
+export * from './cognitive-cost.js';
+export * from './confidence.js';
+export * from './smart-report.js';
+export * from './improvements.js';
+export * from './auto-fix.js';
+/**
+ * Convenience function: estimate max_tokens from spec
+ *
+ * @param spec - OutputFormatSpec object or markdown string
+ * @param options - Estimation options
+ * @returns Estimated max_tokens value
+ */
+export function getMaxTokens(spec, options) {
+    if (!spec)
+        return 0;
+    const parsedSpec = typeof spec === 'string'
+        ? parseOutputFormatSpec(spec)
+        : spec;
+    if (!parsedSpec)
+        return 0;
+    const estimate = estimateSpecTokens(parsedSpec, options);
+    return estimate.total.estimated;
+}

package/dist/tokens/parser.d.ts

@@ -0,0 +1,3 @@
+import type { SystemPart } from './types.js';
+import type { SectionKind } from '../types.js';
+export declare function parseSystemPart(instruction: string | undefined, kind: SectionKind | 'code'): SystemPart | null;

package/dist/tokens/parser.js

@@ -0,0 +1,97 @@
+import { SYSTEM_PART_PATTERNS, INSTRUCTION_SPLIT } from './patterns.js';
+export function parseSystemPart(instruction, kind // Allow 'code' as a special case if needed
+) {
+    if (!instruction)
+        return null;
+    const pattern = SYSTEM_PART_PATTERNS[kind];
+    if (!pattern)
+        return null;
+    const match = instruction.match(pattern);
+    if (!match)
+        return null;
+    // Split into system and guidance parts
+    const parts = instruction.split(INSTRUCTION_SPLIT);
+    const raw = parts[0];
+    const guidance = parts.slice(1).join('. ') || null;
+    const parsed = parseMatchByKind(kind, match);
+    if (!parsed)
+        return null;
+    return { raw, guidance, parsed };
+}
+function parseMatchByKind(kind, match) {
+    switch (kind) {
+        case 'text':
+            return parseTextMatch(match);
+        case 'list':
+        case 'ordered_list':
+            return parseItemsMatch(match);
+        case 'table':
+        case 'ordered_table':
+            return parseTableMatch(match);
+        case 'code':
+            return parseCodeMatch(match);
+        default:
+            return null;
+    }
+}
+function parseTextMatch(match) {
+    const raw = match[1].toLowerCase().replace(/\s+/g, ' ');
+    // Map to canonical LengthValue
+    const lengthMap = {
+        '1 sentence': '1 sentence',
+        '1-2 sentences': '1-2 sentences',
+        '1 paragraph': '1 paragraph',
+        '2-3 paragraphs': '2-3 paragraphs',
+        'brief': 'brief',
+        'moderate': 'moderate',
+        'detailed': 'detailed',
+        'extensive': 'extensive'
+    };
+    const value = lengthMap[raw] || 'moderate';
+    return { type: 'length', value };
+}
+function parseItemsMatch(match) {
+    // match[1] = "at least" (optional)
+    // match[2] = min number
+    // match[3] = max number (optional)
+    return {
+        type: 'items',
+        min: parseInt(match[2]),
+        max: match[3] ? parseInt(match[3]) : null,
+        atLeast: !!match[1]
+    };
+}
+function parseTableMatch(match) {
+    // match[1] = rows "at least" (optional)
+    // match[2] = rows min
+    // match[3] = rows max (optional)
+    // match[4] = columns "at least" (optional)
+    // match[5] = columns min
+    // match[6] = columns max (optional)
+    return {
+        type: 'table',
+        rows: {
+            min: parseInt(match[2]),
+            max: match[3] ? parseInt(match[3]) : null,
+            atLeast: !!match[1],
+            approximate: false
+        },
+        columns: {
+            min: parseInt(match[5]),
+            max: match[6] ? parseInt(match[6]) : null,
+            atLeast: !!match[4],
+            approximate: false
+        }
+    };
+}
+function parseCodeMatch(match) {
+    // match[1] = "~" (optional)
+    // match[2] = min number
+    // match[3] = max number (optional)
+    return {
+        type: 'lines',
+        min: parseInt(match[2]),
+        max: match[3] ? parseInt(match[3]) : null,
+        approximate: !!match[1]
+    };
+}

package/dist/tokens/patterns.d.ts

@@ -0,0 +1,9 @@
+export declare const SYSTEM_PART_PATTERNS: {
+    readonly text: RegExp;
+    readonly list: RegExp;
+    readonly ordered_list: RegExp;
+    readonly table: RegExp;
+    readonly ordered_table: RegExp;
+    readonly code: RegExp;
+};
+export declare const INSTRUCTION_SPLIT: RegExp;

package/dist/tokens/patterns.js

@@ -0,0 +1,20 @@
+// patterns.ts
+export const SYSTEM_PART_PATTERNS = {
+    // TEXT: Enumerated literal strings only
+    text: /^Length:\s*(1\s+sentence|1-2\s+sentences|1\s+paragraph|2-3\s+paragraphs|brief|moderate|detailed|extensive)/i,
+    // LIST/ORDERED-LIST: [optional "at least"] + number + [optional range]
+    // Matches: "3" | "3-5" | "at least 3"
+    list: /^Items:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?/i,
+    ordered_list: /^Items:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?/i,
+    // TABLE: Two numeric patterns (rows and columns)
+    // Matches: "Rows: 3, Columns: 5" | "Rows: 3-5, Columns: at least 2"
+    table: /^Rows:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?,\s*Columns:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?/i,
+    ordered_table: /^Rows:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?,\s*Columns:\s*(?:(at least)\s+)?(\d+)(?:-(\d+))?/i,
+    // CODE: [optional "~"] + number + [optional range]
+    // Matches: "10" | "10-20" | "~50"
+    // Note: SectionKind doesn't include 'code' currently, but we might handle it if it's added.
+    // For now, let's keep it but expect SectionKind to match.
+    code: /^Lines:\s*(~)?(\d+)(?:-(\d+))?/i
+};
+// Separator for splitting system part from guidance
+export const INSTRUCTION_SPLIT = /\.\s+/;

package/dist/tokens/smart-report.d.ts

@@ -0,0 +1,10 @@
+import type { SmartAnalysis, ComplianceLevel } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+/**
+ * Comprehensive smart analysis of spec
+ */
+export declare function analyzeSpec(spec: OutputFormatSpec, targetLevel?: ComplianceLevel): SmartAnalysis;
+/**
+ * Format comprehensive smart report
+ */
+export declare function formatSmartReport(analysis: SmartAnalysis): string;

package/dist/tokens/smart-report.js

@@ -0,0 +1,187 @@
+import { checkSpecCompliance } from './compliance.js';
+import { calculateCognitiveCost } from './cognitive-cost.js';
+import { calculateConfidence } from './confidence.js';
+import { estimateSpecTokens } from './spec-estimator.js';
+/**
+ * Comprehensive smart analysis of spec
+ */
+export function analyzeSpec(spec, targetLevel = 2) {
+    const compliance = checkSpecCompliance(spec, targetLevel);
+    const cognitiveCost = calculateCognitiveCost(spec);
+    const confidence = calculateConfidence(spec);
+    const tokenEstimate = estimateSpecTokens(spec);
+    const recommendations = generateSmartRecommendations(compliance, cognitiveCost, confidence, tokenEstimate);
+    return {
+        spec,
+        compliance,
+        cognitiveCost,
+        confidence,
+        tokenEstimate,
+        recommendations
+    };
+}
+function generateSmartRecommendations(compliance, cost, confidence, estimate) {
+    const recs = [];
+    // High priority: Compliance issues
+    if (!compliance.compliant && compliance.violations.length > 0) {
+        recs.push({
+            priority: 'high',
+            category: 'quality',
+            message: `${compliance.violations.length} sections don't meet L${compliance.level} compliance`,
+            action: 'Add or upgrade system parts in flagged sections'
+        });
+    }
+    // High priority: Low confidence
+    if (confidence.overall < 70) {
+        recs.push({
+            priority: 'high',
+            category: 'confidence',
+            message: `Token estimation confidence is ${confidence.grade} (${confidence.overall.toFixed(0)}%)`,
+            action: confidence.recommendations[0]
+        });
+    }
+    // Medium priority: High cognitive cost
+    if (cost.totalCost > 60) {
+        recs.push({
+            priority: 'medium',
+            category: 'cost',
+            message: `Cognitive cost is high (${cost.totalCost.toFixed(0)}/100)`,
+            action: 'Consider reducing some sections to L2 or L1'
+        });
+    }
+    // Medium priority: Unreasonable token estimate
+    if (estimate.total.estimated > 4000) {
+        recs.push({
+            priority: 'medium',
+            category: 'quality',
+            message: `Estimated ${estimate.total.estimated} tokens - may be too large`,
+            action: 'Consider reducing scope or splitting into multiple prompts'
+        });
+    }
+    // Low priority: Optimization opportunities
+    if (confidence.overall >= 70 && confidence.overall < 90) {
+        recs.push({
+            priority: 'low',
+            category: 'confidence',
+            message: 'Good confidence, but can be improved',
+            action: 'Upgrade a few sections to L3 for better precision'
+        });
+    }
+    // Low priority: Cost optimization
+    if (cost.totalCost < 30 && confidence.overall > 80) {
+        recs.push({
+            priority: 'low',
+            category: 'cost',
+            message: 'Excellent balance of cost and confidence',
+            action: 'No changes needed'
+        });
+    }
+    return recs;
+}
+/**
+ * Format comprehensive smart report
+ */
+export function formatSmartReport(analysis) {
+    const lines = [];
+    lines.push('╔═══════════════════════════════════════════════════╗');
+    lines.push('║         FLEX-MD SMART ANALYSIS REPORT            ║');
+    lines.push('╚═══════════════════════════════════════════════════╝');
+    lines.push('');
+    // Summary Dashboard
+    lines.push('📊 SUMMARY DASHBOARD');
+    lines.push('─'.repeat(50));
+    lines.push(`Compliance:      ${analysis.compliance.compliant ? '✓' : '✗'} L${analysis.compliance.level} ${analysis.compliance.compliant ? 'PASS' : 'FAIL'}`);
+    lines.push(`Confidence:      ${analysis.confidence.grade} (${analysis.confidence.overall.toFixed(0)}%)`);
+    lines.push(`Cognitive Cost:  ${analysis.cognitiveCost.totalCost.toFixed(0)}/100`);
+    lines.push(`Token Estimate:  ${analysis.tokenEstimate.total.estimated} tokens`);
+    lines.push('');
+    // Key Metrics
+    lines.push('📈 KEY METRICS');
+    lines.push('─'.repeat(50));
+    lines.push(`Total Sections:              ${analysis.spec.sections.length}`);
+    lines.push(`With System Parts:           ${analysis.compliance.summary.compliantSections}`);
+    lines.push(`Coverage:                    ${analysis.confidence.bySection.filter(s => s.hasSystemPart).length}/${analysis.spec.sections.length} (${((analysis.confidence.bySection.filter(s => s.hasSystemPart).length / (analysis.spec.sections.length || 1)) * 100).toFixed(0)}%)`);
+    lines.push(`Average Compliance Level:    L${(analysis.compliance.summary.averageLevel || 0).toFixed(1)}`);
+    lines.push('');
+    // Recommendations
+    if (analysis.recommendations.length > 0) {
+        lines.push('💡 RECOMMENDATIONS');
+        lines.push('─'.repeat(50));
+        const highPriority = analysis.recommendations.filter(r => r.priority === 'high');
+        const mediumPriority = analysis.recommendations.filter(r => r.priority === 'medium');
+        const lowPriority = analysis.recommendations.filter(r => r.priority === 'low');
+        if (highPriority.length > 0) {
+            lines.push('🔴 High Priority:');
+            highPriority.forEach(r => {
+                lines.push(`   • ${r.message}`);
+                if (r.action)
+                    lines.push(`     → ${r.action}`);
+            });
+            lines.push('');
+        }
+        if (mediumPriority.length > 0) {
+            lines.push('🟡 Medium Priority:');
+            mediumPriority.forEach(r => {
+                lines.push(`   • ${r.message}`);
+                if (r.action)
+                    lines.push(`     → ${r.action}`);
+            });
+            lines.push('');
+        }
+        if (lowPriority.length > 0) {
+            lines.push('🟢 Low Priority:');
+            lowPriority.forEach(r => {
+                lines.push(`   • ${r.message}`);
+                if (r.action)
+                    lines.push(`     → ${r.action}`);
+            });
+            lines.push('');
+        }
+    }
+    // Section Breakdown
+    lines.push('📋 SECTION BREAKDOWN');
+    lines.push('─'.repeat(50));
+    lines.push('Section                    Level  Confidence  Cost  Tokens');
+    lines.push('─'.repeat(50));
+    analysis.confidence.bySection.forEach((conf, i) => {
+        const cost = analysis.cognitiveCost.perSection[i];
+        const tokens = analysis.tokenEstimate.bySectionName[conf.sectionName];
+        const level = conf.level !== null ? `L${conf.level}` : 'L0';
+        const confStr = `${conf.confidence.toFixed(0)}%`;
+        const costStr = cost ? `${cost.cost.toFixed(1)}` : '0.0';
+        const tokenStr = tokens ? `~${tokens.estimated}` : 'N/A';
+        const name = conf.sectionName.length > 24 ? conf.sectionName.slice(0, 21) + '...' : conf.sectionName.padEnd(24);
+        lines.push(`${name}  ${level.padEnd(5)}  ${confStr.padEnd(10)}  ${costStr.padEnd(4)}  ${tokenStr}`);
+    });
+    lines.push('');
+    // Confidence Factors
+    if (analysis.confidence.factors.length > 0) {
+        lines.push('🎯 CONFIDENCE FACTORS');
+        lines.push('─'.repeat(50));
+        analysis.confidence.factors.forEach(factor => {
+            const icon = factor.impact === 'positive' ? '✓' : factor.impact === 'negative' ? '✗' : '○';
+            const sign = factor.score >= 0 ? '+' : '';
+            lines.push(`${icon} ${factor.factor}: ${sign}${factor.score}`);
+            lines.push(`   ${factor.description}`);
+        });
+        lines.push('');
+    }
+    // Cost Breakdown
+    lines.push('💰 COGNITIVE COST BREAKDOWN');
+    lines.push('─'.repeat(50));
+    lines.push(`Base Cost:        ${analysis.cognitiveCost.breakdown.baseCost.toFixed(1)}`);
+    lines.push(`Complexity Cost:  ${analysis.cognitiveCost.breakdown.complexityCost.toFixed(1)}`);
+    lines.push(`Decision Cost:    ${analysis.cognitiveCost.breakdown.decisionCost.toFixed(1)}`);
+    lines.push(`Total Cost:       ${analysis.cognitiveCost.totalCost.toFixed(1)}/100`);
+    lines.push(`Assessment:       ${analysis.cognitiveCost.recommendation}`);
+    lines.push('');
+    // Token Estimate
+    lines.push('🔢 TOKEN ESTIMATE');
+    lines.push('─'.repeat(50));
+    lines.push(`Estimated:  ${analysis.tokenEstimate.total.estimated} tokens`);
+    lines.push(`Range:      ${analysis.tokenEstimate.total.min} - ${analysis.tokenEstimate.total.max} tokens`);
+    lines.push(`Overhead:   ${analysis.tokenEstimate.overhead} tokens`);
+    lines.push(`Confidence: ${analysis.confidence.grade}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/tokens/spec-estimator.d.ts

@@ -0,0 +1,7 @@
+import type { SpecTokenEstimate } from './types.js';
+import type { OutputFormatSpec } from '../types.js';
+export declare function estimateSpecTokens(spec: OutputFormatSpec, options?: {
+    includeOptional?: boolean;
+    safetyMultiplier?: number;
+    strategy?: 'conservative' | 'average' | 'generous';
+}): SpecTokenEstimate;

package/dist/tokens/spec-estimator.js

@@ -0,0 +1,68 @@
+import { parseSystemPart } from './parser.js';
+import { estimateTokens, getFallbackEstimate, TOKEN_CONSTANTS } from './estimator.js';
+export function estimateSpecTokens(spec, options = {}) {
+    const { includeOptional = true, safetyMultiplier = 1.2, strategy = 'average' } = options;
+    const bySectionName = {};
+    let totalEstimated = 0;
+    let totalMin = 0;
+    let totalMax = 0;
+    for (const section of spec.sections) {
+        // Skip optional sections if requested
+        const isRequired = section.required !== false; // Default to required if not explicitly false
+        if (!includeOptional && !isRequired)
+            continue;
+        const kind = section.kind || 'text';
+        const systemPart = parseSystemPart(section.instruction, kind);
+        let estimate;
+        if (systemPart) {
+            estimate = estimateTokens(systemPart);
+        }
+        else {
+            estimate = getFallbackEstimate(kind, isRequired);
+        }
+        // Apply optional section discount
+        if (!isRequired) {
+            estimate = {
+                estimated: Math.round(estimate.estimated * 0.6),
+                min: Math.round(estimate.min * 0.5),
+                max: Math.round(estimate.max * 0.7),
+                confidence: 'low'
+            };
+        }
+        bySectionName[section.name] = estimate;
+        totalEstimated += estimate.estimated;
+        totalMin += estimate.min;
+        totalMax += estimate.max;
+    }
+    // Add overhead
+    const overhead = TOKEN_CONSTANTS.baseOverhead +
+        (spec.sections.length * TOKEN_CONSTANTS.headingOverhead);
+    totalEstimated += overhead;
+    totalMin += overhead;
+    totalMax += overhead;
+    // Apply strategy
+    let finalEstimate;
+    switch (strategy) {
+        case 'conservative':
+            finalEstimate = totalMin;
+            break;
+        case 'generous':
+            finalEstimate = totalMax;
+            break;
+        case 'average':
+        default:
+            finalEstimate = totalEstimated;
+    }
+    // Apply safety multiplier
+    finalEstimate = Math.ceil(finalEstimate * safetyMultiplier);
+    return {
+        total: {
+            estimated: finalEstimate,
+            min: Math.ceil(totalMin * safetyMultiplier),
+            max: Math.ceil(totalMax * safetyMultiplier),
+            confidence: 'medium'
+        },
+        bySectionName,
+        overhead
+    };
+}

package/dist/tokens/types.d.ts

@@ -0,0 +1,185 @@
+import type { SectionKind, OutputFormatSpec as RealOutputFormatSpec } from "../types.js";
+export type ComplianceLevel = 0 | 1 | 2 | 3;
+export type LengthValue = '1 sentence' | '1-2 sentences' | '1 paragraph' | '2-3 paragraphs' | 'brief' | 'moderate' | 'detailed' | 'extensive';
+export interface NumericSpec {
+    min: number;
+    max: number | null;
+    atLeast: boolean;
+    approximate: boolean;
+}
+export type ParsedSystemPart = {
+    type: 'length';
+    value: LengthValue;
+} | {
+    type: 'items';
+    min: number;
+    max: number | null;
+    atLeast: boolean;
+} | {
+    type: 'table';
+    rows: NumericSpec;
+    columns: NumericSpec;
+} | {
+    type: 'lines';
+    min: number;
+    max: number | null;
+    approximate: boolean;
+};
+export interface SystemPart {
+    raw: string;
+    guidance: string | null;
+    parsed: ParsedSystemPart;
+}
+export interface TokenEstimate {
+    estimated: number;
+    min: number;
+    max: number;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface SpecTokenEstimate {
+    total: TokenEstimate;
+    bySectionName: Record<string, TokenEstimate>;
+    overhead: number;
+}
+export interface ComplianceViolation {
+    sectionName: string;
+    kind: SectionKind;
+    level: ComplianceLevel;
+    message: string;
+}
+export interface ComplianceReport {
+    compliant: boolean;
+    level: ComplianceLevel;
+    violations: ComplianceViolation[];
+    summary: {
+        totalSections: number;
+        compliantSections: number;
+        averageLevel: number;
+    };
+}
+export interface CostFactor {
+    factor: string;
+    impact: number;
+    description: string;
+}
+export interface CostBreakdown {
+    baseCost: number;
+    complexityCost: number;
+    decisionCost: number;
+    totalSections: number;
+}
+export interface SectionCost {
+    sectionName: string;
+    cost: number;
+    level: ComplianceLevel | null;
+    factors: CostFactor[];
+}
+export interface CognitiveCost {
+    totalCost: number;
+    perSection: SectionCost[];
+    breakdown: CostBreakdown;
+    recommendation: string;
+}
+export interface LevelCostComparison {
+    byLevel: Record<ComplianceLevel, number>;
+    recommendation: string;
+}
+export interface ConfidenceFactor {
+    factor: string;
+    impact: 'positive' | 'negative' | 'neutral';
+    score: number;
+    description: string;
+}
+export interface SectionConfidence {
+    sectionName: string;
+    confidence: number;
+    hasSystemPart: boolean;
+    level: ComplianceLevel | null;
+    estimateQuality: 'excellent' | 'good' | 'fair' | 'poor' | 'none';
+}
+export interface ConfidenceScore {
+    overall: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    bySection: SectionConfidence[];
+    factors: ConfidenceFactor[];
+    recommendations: string[];
+}
+export interface SmartRecommendation {
+    priority: 'high' | 'medium' | 'low';
+    category: 'quality' | 'cost' | 'confidence';
+    message: string;
+    action?: string;
+}
+export interface SmartAnalysis {
+    spec: RealOutputFormatSpec;
+    compliance: ComplianceReport;
+    cognitiveCost: CognitiveCost;
+    confidence: ConfidenceScore;
+    tokenEstimate: SpecTokenEstimate;
+    recommendations: SmartRecommendation[];
+}
+export interface ImprovementImpact {
+    confidenceGain: number;
+    cognitiveLoadChange: number;
+    estimateAccuracyGain: number;
+    description: string;
+}
+export interface Improvement {
+    sectionName: string;
+    priority: 'critical' | 'high' | 'medium' | 'low';
+    category: 'missing' | 'vague' | 'upgrade' | 'fix' | 'optimize';
+    issue: string;
+    impact: ImprovementImpact;
+    suggestion: string;
+    before: string;
+    after: string;
+    effort: 'trivial' | 'easy' | 'moderate' | 'hard';
+    autoFixable: boolean;
+}
+export interface AntiPattern {
+    sectionName: string;
+    pattern: string;
+    severity: 'error' | 'warning' | 'info';
+    why: string;
+    fix: string;
+    example: string;
+}
+export interface Optimization {
+    type: 'consolidate' | 'simplify' | 'rebalance' | 'split';
+    scope: 'section' | 'spec';
+    description: string;
+    benefit: string;
+    effort: 'trivial' | 'easy' | 'moderate' | 'hard';
+    sections?: string[];
+}
+export interface ImprovementSummary {
+    totalImprovements: number;
+    criticalCount: number;
+    potentialConfidenceGain: number;
+    quickWinCount: number;
+    estimatedEffort: string;
+}
+export interface ImprovementAnalysis {
+    improvements: Improvement[];
+    quickWins: Improvement[];
+    antiPatterns: AntiPattern[];
+    optimizations: Optimization[];
+    summary: ImprovementSummary;
+}
+export interface AppliedFix {
+    sectionName: string;
+    improvement: string;
+    before: string;
+    after: string;
+}
+export interface SkippedFix {
+    sectionName: string;
+    reason: string;
+    manualActionNeeded: string;
+}
+export interface AutoFixResult {
+    fixed: RealOutputFormatSpec;
+    appliedFixes: AppliedFix[];
+    skippedFixes: SkippedFix[];
+    summary: string;
+}

package/dist/tokens/validator.d.ts

@@ -0,0 +1,16 @@
+import type { OutputFormatSpec } from '../types.js';
+export interface ValidationError {
+    sectionName: string;
+    message: string;
+    instruction: string;
+}
+export interface ValidationWarning {
+    sectionName: string;
+    message: string;
+}
+export interface TokenValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+export declare function validateSystemParts(spec: OutputFormatSpec): TokenValidationResult;