🔍 Nellie HTML Validator

A shared HTML validation engine for Nellie VSCode extension and desktop app, providing consistent validation across all platforms.

📦 Installation

npm install nellie-html-validator

🚀 Quick Start

const { adapters, mainValidator } = require('nellie-html-validator');

// Quick validation
const result = await mainValidator('test.html', htmlContent);
console.log(`Found ${result.diagnostics.length} issues`);

🎯 Platform Adapters

VSCode Extension Integration

const { adapters } = require('nellie-html-validator');

// In your VSCode extension
async function validateDocument(document, vscode) {
    const diagnostics = await adapters.vscode.validateDocument(document, vscode);
    return diagnostics;
}

// Register diagnostics provider
vscode.languages.registerCodeActionsProvider('html', {
    async provideCodeActions(document, range, context) {
        const diagnostics = await adapters.vscode.validateDocument(document, vscode);
        return adapters.vscode.createCodeActions(diagnostics, document);
    }
});

Electron App Integration

const { adapters } = require('nellie-html-validator');

// Setup IPC handlers in main process
adapters.electron.setupIPCHandlers(ipcMain, mainWindow);

// Validate HTML in main process
const result = await adapters.electron.validateHTML(uri, content, options);

// Batch validation
const results = await adapters.electron.validateBatch(files, options);

Node.js Integration

const { adapters } = require('nellie-html-validator');

// Direct validation
const result = await adapters.node.validateFile('./test.html');

// With custom options
const result = await adapters.node.validateContent(htmlContent, {
    checkDCD: true,
    checkScripts: true,
    checkEntities: true,
    checkArt: false, // Skip S3-dependent checks
    checkHeadings: true
});

🔧 Validation Options

const options = {
    basicValidationOnly: false,    // Only HTML syntax validation
    checkDCD: true,               // Digital Citizenship & Design checks
    checkScripts: true,           // Required script validation
    checkEntities: true,          // HTML entity validation
    checkArt: true,              // Media/asset validation (requires S3)
    checkHeadings: true,         // Heading structure validation
    
    // S3 configuration (for art validation)
    s3Client: s3ClientInstance,
    aws: awsConfig,
    
    // Progress callback
    progressCallback: (progress) => console.log(`${progress}% complete`)
};

📋 Validation Results

const result = {
    diagnostics: [
        {
            message: "Edwin CSS is missing",
            severity: "error",        // "error" | "warning" | "info"
            range: {
                start: { line: 0, character: 0 },
                end: { line: 0, character: 10 }
            },
            source: "nellie-validator",
            code: "missing-edwin-css"
        }
    ]
};

🎨 Available Validators

• htmlChecker: Basic HTML syntax validation using HTMLHint
• dcdChecker: Digital Citizenship & Design compliance
• headingsChecker: Heading structure and hierarchy
• scriptChecker: Required JavaScript/CSS validation
• entityChecker: HTML entity validation
• artChecker: Media and asset validation (S3-dependent)

🔄 Migration Guide

From Existing VSCode Extension

Before:

// Old validation code
function validateHTML(document) {
    const diagnostics = [];
    // 500+ lines of validation logic...
    return diagnostics;
}

After:

// New shared validation
const { adapters } = require('nellie-html-validator');

async function validateHTML(document, vscode) {
    return await adapters.vscode.validateDocument(document, vscode);
}

Benefits of Migration

✅ Consistency: Identical validation across desktop app and VSCode
✅ Maintenance: Update once, deploy everywhere
✅ Features: All validation rules automatically available
✅ Performance: Optimized validation engine

📚 Advanced Usage

Custom Validation Pipeline

const { validators, MinimalDocument } = require('nellie-html-validator');

// Create document
const document = new MinimalDocument('test.html', htmlContent);

// Run specific validators
const htmlIssues = validators.htmlChecker(document);
const scriptIssues = await validators.scriptChecker(document);
const entityIssues = validators.entityChecker.collectEntityDiagnostics(document);

// Combine results
const allIssues = [...htmlIssues, ...scriptIssues, ...entityIssues];

Batch Processing

const files = [
    { uri: 'file1.html', content: '...' },
    { uri: 'file2.html', content: '...' }
];

const results = await adapters.electron.validateBatch(files, options);
console.log(`Processed ${results.length} files`);

🐛 Error Handling

try {
    const result = await adapters.vscode.validateDocument(document, vscode);
    // Handle successful validation
} catch (error) {
    if (error.code === 'MISSING_S3_CONFIG') {
        // Handle S3 configuration issues
        console.warn('Art validation disabled: S3 not configured');
    } else {
        // Handle other validation errors
        console.error('Validation failed:', error.message);
    }
}

📋 VSCode Extension Checklist

• [ ] Install nellie-html-validator package
• [ ] Import adapters.vscode in your extension
• [ ] Replace existing validation with validateDocument()
• [ ] Register diagnostics provider
• [ ] Add code actions support (optional)
• [ ] Test with sample HTML files
• [ ] Update package.json dependencies

🔗 Links

• NPM Package
• GitHub Repository
• VSCode Extension API

📄 License

MIT License - feel free to use in your projects!