spec-up-t-healthcheck 1.0.0

package/lib/file-opener.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Cross-platform file opener utility
+ * 
+ * This module provides functionality to open files and URLs in the user's default
+ * application across different operating systems. It handles platform-specific
+ * commands and provides consistent error handling and feedback.
+ * 
+ * @author spec-up-t-healthcheck
+ 
+ */
+
+import { spawn } from 'child_process';
+import { platform } from 'os';
+import { existsSync } from 'fs';
+
+/**
+ * Opens a file or URL in the default application.
+ * 
+ * This function automatically detects the operating system and uses the appropriate
+ * command to open files or URLs. It provides cross-platform compatibility for
+ * opening HTML files in the default browser.
+ * 
+ * @param {string} target - The file path or URL to open
+ * @returns {Promise<boolean>} Promise that resolves to true if successful, false otherwise
+ * 
+ * @example
+ * ```javascript
+ * // Open an HTML file
+ * const success = await openFile('/path/to/report.html');
+ * if (success) {
+ *   console.log('Report opened in browser');
+ * }
+ * 
+ * // Open a URL
+ * await openFile('https://example.com');
+ * ```
+ */
+export async function openFile(target) {
+  return new Promise((resolve) => {
+    // Validate file exists if it's a local path
+    if (!target.startsWith('http') && !existsSync(target)) {
+      console.error(`File does not exist: ${target}`);
+      resolve(false);
+      return;
+    }
+
+    const platformType = platform();
+    const commands = {
+      'darwin': ['open', target],
+      'win32': ['cmd', '/c', 'start', '', target],
+      'default': ['xdg-open', target]
+    };
+    
+    const [command, ...args] = commands[platformType] || commands.default;
+
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore'
+    });
+
+    // Simple error handling - resolve false on error, true on success
+    child.on('error', () => resolve(false));
+    child.on('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+/**
+ * Opens an HTML file in the default browser.
+ * 
+ * This is a convenience wrapper around openFile specifically for HTML files.
+ * It provides additional validation and more specific error messages for HTML content.
+ * 
+ * @param {string} htmlFilePath - Path to the HTML file to open
+ * @returns {Promise<boolean>} Promise that resolves to true if successful, false otherwise
+ * 
+ * @example
+ * ```javascript
+ * const reportPath = '/tmp/health-report.html';
+ * const opened = await openHtmlFile(reportPath);
+ * if (!opened) {
+ *   console.error('Failed to open HTML report');
+ * }
+ * ```
+ */
+export async function openHtmlFile(htmlFilePath) {
+  if (!htmlFilePath.toLowerCase().endsWith('.html') && !htmlFilePath.toLowerCase().endsWith('.htm')) {
+    console.warn('Warning: File does not appear to be an HTML file');
+  }
+  
+  return await openFile(htmlFilePath);
+}
+
+/**
+ * Gets the platform-specific command for opening files.
+ * 
+ * This utility function returns the command name that would be used to open files
+ * on the current platform. This is useful for debugging or displaying information to users.
+ * NOTE: This function only returns the command name as a string - it does NOT open files.
+ * To actually open files, use openFile() or openHtmlFile() instead.
+ * 
+ * @returns {string} The platform-specific open command name
+ * 
+ * @example
+ * ```javascript
+ * const commandName = getOpenCommand();
+ * console.log(`Using command: ${commandName}`); // e.g., "open" on macOS
+ * 
+ * // To actually open a file, use openFile() or openHtmlFile():
+ * const success = await openFile('report.html');
+ * const success2 = await openHtmlFile('report.html');
+ * ```
+ */
+export function getOpenCommand() {
+  const platformType = platform();
+  
+  switch (platformType) {
+    case 'darwin':
+      return 'open';
+    case 'win32':
+      return 'start';
+    default:
+      return 'xdg-open';
+  }
+}

package/lib/formatters.js

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Output formatters for health check results
+ * 
+ * This module provides various formatting options for health check results,
+ * including human-readable text output with icons, structured JSON output,
+ * and interactive HTML reports with Bootstrap styling.
+ * The formatters support customization options and maintain consistent styling.
+ * 
+ * @author spec-up-t-healthcheck
+ 
+ */
+
+import { generateHtmlReport } from './html-formatter.js';
+
+/**
+ * Formats health check results as human-readable text with emojis and structured layout.
+ * 
+ * This formatter creates a comprehensive text report that's suitable for console output
+ * or text files. It includes a summary section, overall status, and detailed results
+ * for each individual check. The output uses Unicode emojis for visual clarity.
+ * 
+ * @param {import('./health-checker.js').HealthCheckReport} healthCheckOutput - The complete health check report
+ * @param {boolean} [useColors=false] - Whether to include ANSI color codes (reserved for future use)
+ * @returns {string} Formatted text report ready for display or logging
+ * 
+ * @example
+ * ```javascript
+ * const report = await runHealthChecks(provider);
+ * const textOutput = formatResultsAsText(report);
+ * console.log(textOutput);
+ * 
+ * // Example output:
+ * // 📋 Spec-up-t Health Check Report
+ * // Generated: 9/18/2025, 10:30:00 AM
+ * // 
+ * // Repository: /path/to/spec
+ * // 
+ * // 📊 Summary
+ * // Total checks: 2
+ * // ✓ Passed: 2
+ * // ✗ Failed: 0
+ * // Score: 100%
+ * ```
+ */
+export function formatResultsAsText(healthCheckOutput, useColors = false) {
+  const { results, summary, timestamp, provider } = healthCheckOutput;
+  
+  let output = [];
+
+  output.push('📋 Spec-up-t Health Check Report');
+  output.push(`Generated: ${new Date(timestamp).toLocaleString()}`);
+  output.push('');
+
+  if (provider.repoPath) {
+    output.push(`Repository: ${provider.repoPath}`);
+  }
+  output.push('');
+
+  output.push('📊 Summary');
+  output.push(`Total checks: ${summary.total}`);
+  output.push(`✓ Passed: ${summary.passed}`);
+  output.push(`✗ Failed: ${summary.failed}`);
+  if (summary.warnings > 0) output.push(`⚠ Warnings: ${summary.warnings}`);
+  if (summary.skipped > 0) output.push(`○ Skipped: ${summary.skipped}`);
+  output.push(`Score: ${Math.round(summary.score)}%`);
+  output.push('');
+
+  if (summary.hasErrors) {
+    output.push('❌ Overall Status: FAILED');
+  } else if (summary.hasWarnings) {
+    output.push('⚠️  Overall Status: PASSED WITH WARNINGS');
+  } else {
+    output.push('✅ Overall Status: PASSED');
+  }
+  output.push('');
+
+  output.push('📝 Detailed Results');
+  output.push('');
+
+  results.forEach((result, index) => {
+    const statusIcon = {
+      pass: '✓',
+      fail: '✗',
+      warn: '⚠',
+      skip: '○'
+    }[result.status];
+
+    output.push(`${index + 1}. ${statusIcon} ${result.check}`);
+    output.push(`   ${result.message}`);
+    
+    if (result.details && Object.keys(result.details).length > 0) {
+      if (result.details.missingFields) {
+        output.push(`   Missing fields: ${result.details.missingFields.join(', ')}`);
+      }
+      if (result.details.count) {
+        output.push(`   Files found: ${result.details.count}`);
+      }
+      if (result.details.packageData) {
+        output.push(`   Package: ${result.details.packageData.name}@${result.details.packageData.version}`);
+      }
+    }
+    
+    output.push('');
+  });
+
+  return output.join('\n');
+}
+
+/**
+ * Formats health check results as structured JSON with optional pretty-printing.
+ * 
+ * This formatter converts the health check report to JSON format, making it suitable
+ * for programmatic consumption, API responses, or storage. The output maintains the
+ * complete structure of the original report with configurable indentation.
+ * 
+ * @param {import('./health-checker.js').HealthCheckReport} healthCheckOutput - The complete health check report
+ * @param {number} [indent=2] - Number of spaces for JSON indentation (0 for compact output)
+ * @returns {string} JSON-formatted string representation of the health check report
+ * 
+ * @example
+ * ```javascript
+ * const report = await runHealthChecks(provider);
+ * 
+ * // Pretty-printed JSON (default)
+ * const prettyJson = formatResultsAsJson(report);
+ * 
+ * // Compact JSON
+ * const compactJson = formatResultsAsJson(report, 0);
+ * 
+ * // Custom indentation
+ * const customJson = formatResultsAsJson(report, 4);
+ * 
+ * // Parse back to object
+ * const parsedReport = JSON.parse(prettyJson);
+ * ```
+ */
+export function formatResultsAsJson(healthCheckOutput, indent = 2) {
+  return JSON.stringify(healthCheckOutput, null, indent);
+}
+
+/**
+ * Formats health check results as an interactive Bootstrap-styled HTML report.
+ * 
+ * This formatter creates a comprehensive HTML document with responsive design,
+ * interactive filtering capabilities, and visual status indicators. The report
+ * follows modern web design patterns and provides an excellent user experience
+ * for reviewing health check results in a browser.
+ * 
+ * @param {import('./health-checker.js').HealthCheckReport} healthCheckOutput - The complete health check report
+ * @param {Object} [options={}] - Configuration options for HTML generation
+ * @param {string} [options.title='Spec-Up-T Health Check Report'] - Custom title for the report
+ * @param {boolean} [options.showPassingByDefault=true] - Whether to show passing checks by default
+ * @param {string} [options.repositoryUrl] - URL to the repository being checked
+ * @returns {string} Complete HTML document ready for saving or displaying
+ * 
+ * @example
+ * ```javascript
+ * const report = await runHealthChecks(provider);
+ * 
+ * // Basic HTML report
+ * const htmlReport = formatResultsAsHtml(report);
+ * 
+ * // Customized HTML report
+ * const customHtml = formatResultsAsHtml(report, {
+ *   title: 'My Project Health Check',
+ *   repositoryUrl: 'https://github.com/user/repo',
+ *   showPassingByDefault: false
+ * });
+ * 
+ * // Save to file
+ * fs.writeFileSync('health-report.html', htmlReport);
+ * ```
+ */
+export function formatResultsAsHtml(healthCheckOutput, options = {}) {
+  return generateHtmlReport(healthCheckOutput, options);
+}