Function validationLoop

src/nodes/validation/core/validation-loop.ts:198–552

(params: ValidationLoopParams)

}

export async function validationLoop(params: ValidationLoopParams): Promise<ValidationLoopResult> {
    // Ensure dependencies are installed before starting validation loop
    ensureValidationDependencies();

    const { protocol, figmaThumbnailUrl, outputDir, workspace } = params;

    if (!protocol || !figmaThumbnailUrl || !outputDir || !workspace) {
        throw new Error('Something wrong in validation loop, missing required parameters...');
    }

    const config: ValidationLoopConfig = {
        ...DEFAULT_VALIDATION_LOOP_CONFIG,
        ...params.config,
    };
    const mode: ValidationMode.ReportOnly | ValidationMode.Full = config.mode ?? ValidationMode.Full;
    const maxIterations = mode === ValidationMode.ReportOnly ? 1 : config.maxIterations;
    const visualizationTool = new VisualizationTool();

    // Variables to track server state (will be initialized in iteration 1)
    let currentServerUrl: string | undefined;
    let serverKey: string | undefined;

    try {
        // Extract unified validation context from protocol (single traversal)
        const validationContext = extractValidationContext(protocol);
        const designOffset: [number, number] = [validationContext.offset.x, validationContext.offset.y];
        if (Math.abs(designOffset[0]) >= 1 || Math.abs(designOffset[1]) >= 1) {
            logger.printInfoLog(`Design offset: (${designOffset[0].toFixed(0)}, ${designOffset[1].toFixed(0)} px)`);
        }

        // Extract component paths from context (already resolved to absolute filesystem paths)
        const resolvedComponentPaths = extractComponentPaths(validationContext, workspace);

        // Build element registry for compatibility with existing APIs
        const elementRegistry = toElementMetadataRegistry(validationContext);

        // Download and cache Figma thumbnail once to avoid redundant downloads in each iteration
        logger.printInfoLog('Downloading Figma thumbnail (will be cached for all iterations)...');
        const cachedFigmaThumbnailBase64 = await downloadImage(figmaThumbnailUrl, undefined, undefined, true);
        logger.printSuccessLog('Figma thumbnail cached successfully');

        const iterations: IterationLog[] = [];
        const componentHistory: ComponentHistory = {};
        let previousScreenshotPath: string | undefined;
        let currentMae = -1; // Sentinel value: -1 indicates no measurement yet
        let currentSae = 0;
        let lastMisalignedCount = 0;
        let lastValidationResult: ValidationIterationResult | undefined;
        // Track paths to last iteration's individual screenshots for report reuse
        let lastRenderMarkedPath: string | undefined;
        let lastTargetMarkedPath: string | undefined;

        for (let iteration = 1; iteration <= maxIterations; iteration++) {
            // Use different logging for reportOnly mode
            if (mode === ValidationMode.ReportOnly) {
                logger.printLog(`\n${'='.repeat(60)}`);
                logger.printLog(`Running validation (report-only mode)`);
                logger.printLog(`${'='.repeat(60)}`);