spec-up-t-healthcheck 1.0.0

package/README.md

@@ -0,0 +1,216 @@
+# 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
+
+```bash
+# 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
+```bash
+# 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:
+
+```javascript
+// 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);
+```
+
+```javascript
+// 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
+
+```javascript
+// 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`:
+
+```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**
+
+![HTML Report Features](docs/html-report-preview.png)
+
+## 🔍 Available Health Checks
+
+- **package-json** - Validates package.json structure and required fields
+- **spec-files** - Finds and validates specification markdown files
+
+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
+
+```bash
+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
+
+```javascript
+{
+  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](docs/API.md)
+- [Health Checks Reference](docs/CHECKS.md)
+- [Integration Guide](docs/INTEGRATION.md)
+- [Full Analysis](HEALTH_CHECK_TOOL_ANALYSIS.md)
+
+## 🤝 Contributing
+
+This project follows the spec-up-t ecosystem standards. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+Apache-2.0 - see [LICENSE](LICENSE) file for details.

package/bin/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Command Line Interface for spec-up-t-healthcheck
+ * 
+ * This CLI tool provides a convenient command-line interface for running health checks
+ * on specification repositories. It supports various output formats, check selection,
+ * and file output options. The CLI is built using Commander.js and provides a user-friendly
+ * interface for all health checking functionality.
+ * 
+ * @author spec-up-t-healthcheck
+ 
+ */
+
+import { Command } from 'commander';
+import { createProvider, runHealthChecks, formatResultsAsText, formatResultsAsJson, formatResultsAsHtml } from '../lib/index.js';
+import { openHtmlFile } from '../lib/file-opener.js';
+import { mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+const program = new Command();
+
+program
+  .name('spec-up-t-healthcheck')
+  .description('Health check tool for spec-up-t repositories')
+  .version('1.0.2');
+
+/**
+ * Main 'check' command that performs health checks on a repository.
+ * 
+ * This command creates a provider for the target repository, runs the specified
+ * health checks, and outputs the results in the requested format. It supports
+ * both local and remote repositories (when implemented) and provides flexible
+ * output options.
+ * 
+ * Exit codes:
+ * - 0: All checks passed
+ * - 1: One or more checks failed or command error
+ * - 2: Checks passed but with warnings
+ * 
+ * @example
+ * ```bash
+ * # Basic usage
+ * spec-up-t-healthcheck check ./my-repo
+ * 
+ * # Specific checks only
+ * spec-up-t-healthcheck check ./my-repo --checks package-json
+ * 
+ * # JSON output to file
+ * spec-up-t-healthcheck check ./my-repo --format json --output report.json
+ * ```
+ */
+program
+  .command('check')
+  .description('Run health checks on a repository')
+  .argument('<target>', 'Repository path (local) or URL (remote)')
+  .option('-c, --checks <checks>', 'Comma-separated list of checks to run (package-json,spec-files)')
+  .option('-f, --format <format>', 'Output format (text|json|html)', 'text')
+  .option('-o, --output <file>', 'Output file path')
+  .option('--no-open', 'Don\'t automatically open HTML reports in browser')
+  .action(async (target, options) => {
+    try {
+      console.log(`\n🔍 Checking: ${target}\n`);
+      
+      // Parse checks option
+      const checks = options.checks ? options.checks.split(',').map(c => c.trim()) : undefined;
+      
+      // Create provider and run checks
+      const provider = createProvider(target);
+      const results = await runHealthChecks(provider, { checks });
+      
+      // Format output based on requested format
+      let output;
+      let defaultOutputFile;
+      
+      if (options.format === 'json') {
+        output = formatResultsAsJson(results, 2);
+        defaultOutputFile = `health-check-${Date.now()}.json`;
+      } else if (options.format === 'html') {
+        // For HTML, determine repository URL if possible
+        let repositoryUrl;
+        if (provider.repoPath && !provider.repoPath.startsWith('/')) {
+          repositoryUrl = provider.repoPath; // Assume it's a URL
+        }
+        
+        output = formatResultsAsHtml(results, {
+          title: `Health Check Report - ${target}`,
+          repositoryUrl
+        });
+        defaultOutputFile = `health-check-${Date.now()}.html`;
+      } else {
+        output = formatResultsAsText(results);
+        defaultOutputFile = `health-check-${Date.now()}.txt`;
+      }
+      
+      // Determine output file path
+      let outputFile = options.output;
+      if (options.format === 'html' && !outputFile) {
+        // For HTML format, create a default output file in .cache directory
+        const cacheDir = join(process.cwd(), '.cache');
+        if (!existsSync(cacheDir)) {
+          mkdirSync(cacheDir, { recursive: true });
+        }
+        outputFile = join(cacheDir, defaultOutputFile);
+      }
+      
+      // Output results
+      if (outputFile) {
+        const fs = await import('fs/promises');
+        
+        // Ensure output directory exists
+        const outputDir = dirname(outputFile);
+        if (!existsSync(outputDir)) {
+          mkdirSync(outputDir, { recursive: true });
+        }
+        
+        await fs.writeFile(outputFile, output);
+        console.log(`✅ Results written to ${outputFile}`);
+        
+        // Automatically open HTML files in browser (unless disabled)
+        if (options.format === 'html' && options.open !== false) {
+          console.log('🌐 Opening report in browser...');
+          const opened = await openHtmlFile(outputFile);
+          if (!opened) {
+            console.log('💡 Could not automatically open browser. Please open the file manually:');
+            console.log(`   ${outputFile}`);
+          }
+        }
+      } else {
+        console.log(output);
+      }
+      
+      // Exit with appropriate code
+      if (results.summary.hasErrors) {
+        process.exit(1);
+      } else if (results.summary.hasWarnings) {
+        process.exit(2);
+      }
+      
+    } catch (error) {
+      console.error(`❌ Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * 'list-checks' command that displays available health checks.
+ * 
+ * This informational command helps users discover what health checks are available
+ * and understand what each check validates. It provides descriptions of each check
+ * and examples of how to use them.
+ */
+program
+  .command('list-checks')
+  .description('List available health checks')
+  .action(() => {
+    console.log('📋 Available Health Checks:\n');
+    console.log('1. package-json - Validates package.json structure and required fields');
+    console.log('2. spec-files   - Finds and validates specification markdown files');
+    console.log('\nUsage: spec-up-t-healthcheck check <target> --checks package-json,spec-files');
+  });
+
+/**
+ * 'example' command that demonstrates CLI usage patterns.
+ * 
+ * This command provides practical examples of how to use the CLI tool
+ * with different options and scenarios. It helps users understand the
+ * available command-line options and common usage patterns.
+ */
+program
+  .command('example')
+  .description('Show usage examples')
+  .action(() => {
+    console.log('📚 Usage Examples:\n');
+    console.log('Local repository:');
+    console.log('  spec-up-t-healthcheck check ./my-spec-repo\n');
+    console.log('Specific checks only:');
+    console.log('  spec-up-t-healthcheck check ./repo --checks package-json\n');
+    console.log('JSON output:');
+    console.log('  spec-up-t-healthcheck check ./repo --format json\n');
+    console.log('HTML report (auto-opens in browser):');
+    console.log('  spec-up-t-healthcheck check ./repo --format html\n');
+    console.log('Save to specific file:');
+    console.log('  spec-up-t-healthcheck check ./repo --output report.html --format html\n');
+    console.log('HTML report without auto-opening:');
+    console.log('  spec-up-t-healthcheck check ./repo --format html --no-open');
+  });
+
+/**
+ * Parse and execute the command line arguments.
+ * This must be called at the end to process user input.
+ */
+program.parse();

package/bin/demo-html.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Demonstration script for HTML health check reports
+ * 
+ * This script creates sample health check data with various statuses and
+ * generates an HTML report to showcase the Bootstrap styling and interactive
+ * features. It's useful for testing the HTML formatter and demonstrating
+ * the visual appearance of health check reports.
+ * 
+ * @author spec-up-t-healthcheck
+
+ */
+
+import { formatResultsAsHtml } from '../lib/formatters.js';
+import { openHtmlFile } from '../lib/file-opener.js';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Creates sample health check data for demonstration purposes.
+ * 
+ * This function generates realistic health check results with various
+ * statuses to showcase how the HTML formatter handles different scenarios.
+ * 
+ * @returns {import('../lib/health-checker.js').HealthCheckReport} Mock health check report
+ */
+function createSampleHealthCheckData() {
+  const timestamp = new Date().toISOString();
+  
+  const results = [
+    {
+      check: 'package-json-exists',
+      status: 'pass',
+      message: 'package.json file found and valid',
+      timestamp,
+      details: {
+        packageData: {
+          name: 'spec-up-t-healthcheck',
+          version: '1.0.2'
+        }
+      }
+    },
+    {
+      check: 'package-json-required-fields',
+      status: 'pass',
+      message: 'All required fields are present',
+      timestamp,
+      details: {}
+    },
+    {
+      check: 'spec-files-present',
+      status: 'pass',
+      message: 'Specification files found',
+      timestamp,
+      details: {
+        count: 3
+      }
+    },
+    {
+      check: 'readme-exists',
+      status: 'pass',
+      message: 'README.md file is present',
+      timestamp,
+      details: {}
+    },
+    {
+      check: 'license-check',
+      status: 'warn',
+      message: 'License file not found - consider adding a LICENSE file',
+      timestamp,
+      details: {}
+    },
+    {
+      check: 'git-ignore-validation',
+      status: 'fail',
+      message: '.gitignore file is missing or incomplete',
+      timestamp,
+      details: {
+        missingFields: ['node_modules', '.cache', '*.log']
+      }
+    },
+    {
+      check: 'dependency-security',
+      status: 'warn',
+      message: 'Some dependencies have known vulnerabilities',
+      timestamp,
+      details: {}
+    },
+    {
+      check: 'typescript-config',
+      status: 'skip',
+      message: 'TypeScript not detected, skipping config validation',
+      timestamp,
+      details: {}
+    }
+  ];
+
+  // Calculate summary
+  const passed = results.filter(r => r.status === 'pass').length;
+  const failed = results.filter(r => r.status === 'fail').length;
+  const warnings = results.filter(r => r.status === 'warn').length;
+  const skipped = results.filter(r => r.status === 'skip').length;
+  
+  const summary = {
+    total: results.length,
+    passed,
+    failed,
+    warnings,
+    skipped,
+    score: Math.round((passed / results.length) * 100),
+    hasErrors: failed > 0,
+    hasWarnings: warnings > 0
+  };
+
+  return {
+    results,
+    summary,
+    timestamp,
+    provider: {
+      type: 'local',
+      repoPath: '/Users/demo/my-spec-project'
+    }
+  };
+}
+
+/**
+ * Main function that generates and opens the sample HTML report.
+ */
+async function generateSampleReport() {
+  console.log('🎨 Generating sample HTML health check report...\n');
+  
+  // Create sample data
+  const sampleData = createSampleHealthCheckData();
+  
+  // Generate HTML report with custom options
+  const htmlContent = formatResultsAsHtml(sampleData, {
+    title: 'Sample Spec-Up-T Health Check Report',
+    repositoryUrl: 'https://github.com/blockchain-bird/spec-up-t-sample',
+    showPassingByDefault: true
+  });
+  
+  // Ensure output directory exists
+  const outputDir = join(process.cwd(), '.cache');
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  
+  // Write HTML file
+  const outputFile = join(outputDir, `sample-health-report-${Date.now()}.html`);
+  writeFileSync(outputFile, htmlContent);
+  
+  console.log(`✅ Sample report generated: ${outputFile}`);
+  console.log('\n📊 Sample Report Contents:');
+  console.log(`   Total checks: ${sampleData.summary.total}`);
+  console.log(`   ✓ Passed: ${sampleData.summary.passed}`);
+  console.log(`   ✗ Failed: ${sampleData.summary.failed}`);
+  console.log(`   ⚠ Warnings: ${sampleData.summary.warnings}`);
+  console.log(`   ○ Skipped: ${sampleData.summary.skipped}`);
+  console.log(`   Score: ${sampleData.summary.score}%`);
+  
+  console.log('\n🌐 Opening sample report in browser...');
+  const opened = await openHtmlFile(outputFile);
+  
+  if (opened) {
+    console.log('✅ Sample report opened successfully!');
+  } else {
+    console.log('⚠️  Could not automatically open browser. Please open manually:');
+    console.log(`   ${outputFile}`);
+  }
+  
+  console.log('\n🎯 Features demonstrated in the sample report:');
+  console.log('   • Bootstrap responsive design');
+  console.log('   • Interactive passing/failing filter toggle');
+  console.log('   • Color-coded status indicators');
+  console.log('   • Detailed health score calculation');
+  console.log('   • Professional card-based layout');
+  console.log('   • Repository information display');
+  console.log('   • Various check result types (pass/fail/warn/skip)');
+}
+
+// Run the sample generator
+generateSampleReport().catch(error => {
+  console.error('❌ Error generating sample report:', error);
+  process.exit(1);
+});

package/bin/simple-test.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Simple test utility for basic functionality validation
+ * 
+ * This standalone test script provides a lightweight way to validate basic
+ * functionality without complex imports or dependencies. It performs fundamental
+ * checks on the current environment and repository structure to ensure the
+ * health check tool can operate correctly.
+ * 
+ * The script is designed to be self-contained and can run independently
+ * of the main library code, making it useful for troubleshooting and
+ * basic environment validation.
+ * 
+ * @author spec-up-t-healthcheck
+ */
+
+/**
+ * Performs basic environment and repository validation checks.
+ * 
+ * This function validates:
+ * - Current working directory access
+ * - package.json existence and content
+ * - Basic Node.js functionality
+ * - Repository identification
+ * 
+ * The checks are designed to be independent of the main health check
+ * library and provide a foundation for more complex validation.
+ */
+async function runBasicHealthCheck() {
+  console.log('🔍 Spec-Up-T Health Check Tool v1.0.0');
+  console.log('');
+  console.log('Available Health Check Categories:');
+  console.log('  ✅ repository (Basic repository checks)');
+  console.log('  ✅ configuration (3 checks)');
+  console.log('  ✅ structure (Basic structure checks)');
+  console.log('');
+  console.log('📋 Basic functionality test:');
+
+  try {
+    // Test basic Node.js functionality
+    const fs = await import('fs/promises');
+    const path = await import('path');
+    
+    const currentDir = process.cwd();
+    console.log(`  ✓ Working directory: ${path.basename(currentDir)}`);
+    
+    // Check if package.json exists
+    try {
+      await fs.access('package.json');
+      console.log('  ✓ package.json found');
+    } catch {
+      console.log('  ✗ package.json not found');
+    }
+    
+    // Check if we're in a spec-up-t healthcheck repo
+    const packageContent = await fs.readFile('package.json', 'utf-8');
+    const pkg = JSON.parse(packageContent);
+    
+    if (pkg.name === 'spec-up-t-healthcheck') {
+      console.log('  ✅ Running in spec-up-t-healthcheck repository');
+      console.log(`  ✓ Version: ${pkg.version}`);
+    } else {
+      console.log(`  ℹ️  Running in: ${pkg.name || 'unknown project'}`);
+    }
+    
+    console.log('');
+    console.log('✅ Basic health check tool is working!');
+    console.log('');
+    console.log('Next: Implement full health check logic');
+    
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Execute the basic health check
+runBasicHealthCheck();