Spec-Up-T Health Check Tool

A modular npm tool for performing comprehensive health checks on spec-up-t repositories. Works across multiple environments: Node.js, browsers, and CLI with beautiful HTML reports.

🚀 Quick Start

# Install globally
npm install -g spec-up-t-healthcheck

# Basic health check
npx spec-up-t-healthcheck check ./my-spec-repo

# Generate HTML report (opens in browser)
npx spec-up-t-healthcheck check ./my-spec-repo --format html

# Save to specific file
npx spec-up-t-healthcheck check . --format html --output my-report.html

📦 Installation & Usage

CLI Usage

# Text output (default)
spec-up-t-healthcheck check .

# JSON output
spec-up-t-healthcheck check . --format json

# HTML report with Bootstrap styling
spec-up-t-healthcheck check . --format html

# Specific checks only
spec-up-t-healthcheck check . --checks package-json,spec-files

# List available checks
spec-up-t-healthcheck list-checks

Direct API Usage (Recommended)

For maximum control and integration into your own tools:

// Basic usage with runHealthChecks
(async () => {
    const { createProvider, runHealthChecks } = await import('spec-up-t-healthcheck');
    const provider = createProvider('.');
    const results = await runHealthChecks(provider, {});
    console.log("🚀 ~ Healthcheck results:", results);
})().catch(console.error);

// Advanced usage with specific checks and formatting
(async () => {
    const { 
        createProvider, 
        runHealthChecks, 
        formatResultsAsHtml,
        formatResultsAsText 
    } = await import('spec-up-t-healthcheck');
    
    const provider = createProvider('./my-project');
    const results = await runHealthChecks(provider, {
        checks: ['package-json', 'spec-files']
    });
    
    // Check results
    console.log(`Health Score: ${results.summary.score}%`);
    console.log(`Passed: ${results.summary.passed}/${results.summary.total}`);
    
    if (results.summary.hasErrors) {
        console.error('❌ Some checks failed');
        console.log(formatResultsAsText(results));
    } else {
        console.log('✅ All checks passed!');
    }
    
    // Generate HTML report
    const htmlReport = formatResultsAsHtml(results, {
        title: 'My Project Health Check',
        repositoryUrl: 'https://github.com/user/repo'
    });
    
    // Save HTML report
    await import('fs/promises').then(fs => 
        fs.writeFile('health-report.html', htmlReport)
    );
})().catch(console.error);

Convenient High-Level API

// Simplified convenience function
import { healthCheck, formatResultsAsHtml } from 'spec-up-t-healthcheck';

const report = await healthCheck('.', {
    checks: ['package-json', 'spec-files']
});

console.log(`Health score: ${report.summary.score}%`);
if (report.summary.hasErrors) {
    console.error('Some health checks failed');
}

npm Scripts Integration

Add to your package.json:

{
  "scripts": {
    "healthcheck": "spec-up-t-healthcheck check .",
    "healthcheck:html": "spec-up-t-healthcheck check . --format html",
    "healthcheck:ci": "spec-up-t-healthcheck check . --format json"
  }
}

🎨 HTML Reports

The HTML format generates beautiful, interactive reports with:

• Bootstrap 5.3 responsive design
• Interactive filtering (show/hide passing checks)
• Color-coded status indicators
• Health score visualization
• Professional card-based layout
• Repository information integration

🔍 Available Health Checks

• package-json - Validates package.json structure and required fields
• spec-files - Finds and validates specification markdown files
• specs-json - Validates specs.json configuration file
• external-specs-urls - Validates external specification URLs
• gitignore - Validates .gitignore file
• spec-directory-and-files - Validates spec directory structure
• link-checker - Validates all links in generated HTML output (uses linkinator)

Use spec-up-t-healthcheck list-checks for the complete list.

📊 Output Formats

| Format | Description | Use Case | |--------|-------------|----------| | text | Human-readable console output | Development, debugging | | json | Structured data | CI/CD, automation, APIs | | html | Interactive web report | Presentations, documentation |

🔧 Options Reference

spec-up-t-healthcheck check <target> [options]

Options:
  -c, --checks <checks>     Comma-separated list of checks to run
  -f, --format <format>     Output format: text|json|html (default: text)
  -o, --output <file>       Output file path
  --no-open                 Don't auto-open HTML reports in browser
  -h, --help               Show help

🏗️ API Reference

Core Functions

• createProvider(path) - Create a filesystem provider
• runHealthChecks(provider, options) - Execute health checks
• formatResultsAsText(results) - Format as console text
• formatResultsAsJson(results) - Format as JSON
• formatResultsAsHtml(results, options) - Format as HTML

Result Structure

{
  results: [
    {
      check: 'package-json',
      status: 'pass|fail|warn|skip',
      message: 'Human-readable message',
      timestamp: '2025-09-18T...',
      details: { /* additional data */ }
    }
  ],
  summary: {
    total: 2,
    passed: 2,
    failed: 0,
    warnings: 0,
    skipped: 0,
    score: 100,
    hasErrors: false,
    hasWarnings: false
  },
  timestamp: '2025-09-18T...',
  provider: { type: 'local', repoPath: '.' }
}

📚 Documentation

• API Documentation
• Health Checks Reference
• Integration Guide
• Full Analysis

🤝 Contributing

This project follows the spec-up-t ecosystem standards. See CONTRIBUTING.md for details.

📄 License

Apache-2.0 - see LICENSE file for details.