@jadermme/orus-core/dist/validation/dataCompleteness.d.ts

ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic

/**
 * ORUS Core - Data Completeness Calculation
 *
 * Pure functions for calculating data completeness across pillars and assessments.
 * Helps track progress and guide users toward more reliable assessments.
 *
 * @remarks
 * Data completeness (0-1) indicates:
 * - 0.0 = No data collected
 * - 0.5 = Partial data (subjective or incomplete objective)
 * - 1.0 = Complete data (all required fields populated)
 *
 * Completeness directly impacts:
 * - Assessment confidence
 * - Mode transition eligibility
 * - Recommendation quality
 */
import type { PillarId } from '../types/pillar.js';
import type { PillarAssessment, SixPillarsAssessment } from '../types/assessment.js';
/**
 * Field schema for data completeness calculation
 *
 * @remarks
 * Defines which fields are required for a complete pillar assessment.
 * Verticals can extend this with domain-specific fields.
 */
export interface PillarFieldSchema {
    /**
     * Core fields (always required)
     */
    core: {
        /**
         * Numeric score required
         */
        score: boolean;
        /**
         * Status required
         */
        status: boolean;
        /**
         * Mode required
         */
        mode: boolean;
        /**
         * Confidence required
         */
        confidence: boolean;
    };
    /**
     * Optional enhanced fields
     */
    optional: {
        /**
         * Trend data (improving/stable/declining)
         */
        trend?: boolean;
        /**
         * Insights array
         */
        insights?: boolean;
        /**
         * Recommendations array
         */
        recommendations?: boolean;
        /**
         * Custom metadata
         */
        metadata?: boolean;
    };
}
/**
 * Vertical-specific schema
 *
 * @remarks
 * Each vertical defines required and optional fields for completeness.
 * Core always requires: score, status, mode, confidence.
 */
export interface VerticalSchema {
    /**
     * Schema for each pillar
     */
    pillars: Record<PillarId, PillarFieldSchema>;
    /**
     * Minimum completeness for objective mode (0-1)
     * @default 0.7
     */
    minCompletenessForObjective?: number;
    /**
     * Minimum completeness for hybrid mode (0-1)
     * @default 0.4
     */
    minCompletenessForHybrid?: number;
}
/**
 * Data completeness result for a single pillar
 */
export interface PillarCompletenessResult {
    /**
     * Pillar ID
     */
    pillarId: PillarId;
    /**
     * Overall completeness (0-1)
     */
    completeness: number;
    /**
     * Core fields completeness (0-1)
     */
    coreCompleteness: number;
    /**
     * Optional fields completeness (0-1)
     */
    optionalCompleteness: number;
    /**
     * Missing required fields
     */
    missingFields: string[];
    /**
     * Missing optional fields
     */
    missingOptionalFields: string[];
    /**
     * Whether pillar meets minimum requirements
     */
    meetsMinimumRequirements: boolean;
}
/**
 * Data completeness result for entire assessment
 */
export interface AssessmentCompletenessResult {
    /**
     * Overall completeness across all pillars (0-1)
     */
    overall: number;
    /**
     * Per-pillar completeness
     */
    perPillar: Record<PillarId, PillarCompletenessResult>;
    /**
     * Number of pillars meeting minimum requirements
     */
    completePillars: number;
    /**
     * Number of pillars with partial data
     */
    partialPillars: number;
    /**
     * Number of pillars with no data
     */
    emptyPillars: number;
    /**
     * Suggested next steps for improving completeness
     */
    suggestions: string[];
}
/**
 * Default field schema (universal for all verticals)
 */
export declare const DEFAULT_PILLAR_FIELD_SCHEMA: PillarFieldSchema;
/**
 * Calculates data completeness for a single pillar
 *
 * @param pillar - Pillar assessment to evaluate
 * @param schema - Field schema (optional, uses default if not provided)
 * @returns Completeness result with breakdown
 *
 * @remarks
 * - Pure function: deterministic calculation
 * - Core fields are weighted 70%, optional 30%
 * - Missing required fields = fails minimum requirements
 * - Completeness can still be high without optional fields
 *
 * @example
 * ```typescript
 * const pillar: PillarAssessment = {
 *   pillarId: PillarId.PILLAR_1,
 *   score: 5.0,
 *   status: 'attention',
 *   mode: 'objective',
 *   confidence: 'high',
 *   // trend, insights, recommendations missing
 *   lastUpdated: new Date(),
 *   dataCompleteness: 0.7
 * };
 *
 * const result = calculatePillarCompleteness(pillar);
 * // result.coreCompleteness = 1.0 (all core fields present)
 * // result.optionalCompleteness = 0.0 (no optional fields)
 * // result.completeness ≈ 0.7 (weighted average)
 * ```
 */
export declare function calculatePillarCompleteness(pillar: PillarAssessment, schema?: PillarFieldSchema): PillarCompletenessResult;
/**
 * Calculates data completeness for entire assessment
 *
 * @param assessment - Six pillars assessment
 * @param schema - Vertical schema (optional)
 * @returns Assessment completeness result
 *
 * @remarks
 * - Pure function: deterministic calculation
 * - Overall = average of all pillar completeness
 * - Generates actionable suggestions for improvement
 * - Categorizes pillars by completeness level
 *
 * @example
 * ```typescript
 * const result = calculateAssessmentCompleteness(assessment);
 *
 * console.log(`Overall: ${result.overall * 100}%`);
 * console.log(`Complete pillars: ${result.completePillars}/6`);
 *
 * if (result.suggestions.length > 0) {
 *   console.log('Next steps:', result.suggestions);
 * }
 * ```
 */
export declare function calculateAssessmentCompleteness(assessment: SixPillarsAssessment, schema?: VerticalSchema): AssessmentCompletenessResult;
/**
 * Gets pillars that need more data
 *
 * @param result - Assessment completeness result
 * @param threshold - Minimum acceptable completeness (default 0.7)
 * @returns Pillar IDs needing attention
 *
 * @remarks
 * - Pure function: simple filter
 * - Useful for UI highlighting and user guidance
 *
 * @example
 * ```typescript
 * const result = calculateAssessmentCompleteness(assessment);
 * const needsWork = getIncompletePillars(result, 0.7);
 *
 * needsWork.forEach(pillarId => {
 *   console.log(`${pillarId}: ${result.perPillar[pillarId].completeness * 100}%`);
 * });
 * ```
 */
export declare function getIncompletePillars(result: AssessmentCompletenessResult, threshold?: number): PillarId[];
/**
 * Checks if assessment is ready for a specific mode
 *
 * @param assessment - Six pillars assessment
 * @param targetMode - Desired mode
 * @param schema - Vertical schema (optional)
 * @returns Whether assessment has sufficient data for mode
 *
 * @remarks
 * - Pure function: deterministic check
 * - Uses schema thresholds if provided, otherwise defaults
 * - Complements canTransitionMode from modeLogic
 *
 * @example
 * ```typescript
 * if (isReadyForMode(assessment, 'objective')) {
 *   console.log('Assessment has enough data for objective mode');
 * } else {
 *   console.log('Need more data collection');
 * }
 * ```
 */
export declare function isReadyForMode(assessment: SixPillarsAssessment, targetMode: 'subjective' | 'objective' | 'hybrid', schema?: VerticalSchema): boolean;
//# sourceMappingURL=dataCompleteness.d.ts.map