spec-up-t-healthcheck 1.0.0

package/lib/health-check-registry.js

@@ -0,0 +1,396 @@
+/**
+ * @fileoverview Health check registry system
+ * 
+ * This module provides a registry system for discovering, registering, and managing
+ * health check modules. It enables dynamic loading of health checks and provides
+ * a centralized way to manage available checks without hardcoding dependencies.
+ * 
+ * @author spec-up-t-healthcheck
+ */
+
+import { isValidHealthCheckResult } from './health-check-utils.js';
+
+/**
+ * @typedef {Object} HealthCheckMetadata
+ * @property {string} id - Unique identifier for the health check
+ * @property {string} name - Human-readable name
+ * @property {string} description - Description of what the check validates
+ * @property {function} checkFunction - The actual health check function
+ * @property {string} [category='general'] - Category for grouping checks
+ * @property {number} [priority=100] - Execution priority (lower = higher priority)
+ * @property {string[]} [dependencies=[]] - IDs of checks that must run before this one
+ * @property {boolean} [enabled=true] - Whether the check is enabled by default
+ */
+
+/**
+ * Registry for managing health check modules.
+ * This class provides a centralized system for registering, discovering,
+ * and executing health checks in a modular fashion.
+ */
+export class HealthCheckRegistry {
+  constructor() {
+    /** @type {Map<string, HealthCheckMetadata>} */
+    this.checks = new Map();
+    
+    /** @type {Set<string>} */
+    this.categories = new Set(['general']);
+    
+    /** @type {boolean} */
+    this.autoDiscovered = false;
+  }
+
+  /**
+   * Registers a health check with the registry.
+   * 
+   * @param {HealthCheckMetadata} metadata - The health check metadata
+   * @throws {Error} If the check metadata is invalid or ID already exists
+   * 
+   * @example
+   * ```javascript
+   * registry.register({
+   *   id: 'my-check',
+   *   name: 'My Custom Check',
+   *   description: 'Validates something important',
+   *   checkFunction: async (provider) => { ... }
+   * });
+   * ```
+   */
+  register(metadata) {
+    this.validateMetadata(metadata);
+    
+    if (this.checks.has(metadata.id)) {
+      throw new Error(`Health check with ID '${metadata.id}' is already registered`);
+    }
+
+    // Set defaults for optional fields
+    const fullMetadata = {
+      category: 'general',
+      priority: 100,
+      dependencies: [],
+      enabled: true,
+      ...metadata
+    };
+
+    this.checks.set(metadata.id, fullMetadata);
+    this.categories.add(fullMetadata.category);
+  }
+
+  /**
+   * Validates health check metadata structure.
+   * 
+   * @param {HealthCheckMetadata} metadata - The metadata to validate
+   * @throws {Error} If metadata is invalid
+   * @private
+   */
+  validateMetadata(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+      throw new Error('Health check metadata must be an object');
+    }
+
+    const requiredFields = ['id', 'name', 'description', 'checkFunction'];
+    for (const field of requiredFields) {
+      if (!metadata[field]) {
+        throw new Error(`Health check metadata missing required field: ${field}`);
+      }
+    }
+
+    if (typeof metadata.id !== 'string' || metadata.id.trim() === '') {
+      throw new Error('Health check ID must be a non-empty string');
+    }
+
+    if (typeof metadata.checkFunction !== 'function') {
+      throw new Error('Health check function must be a function');
+    }
+
+    // Validate optional fields if present
+    if (metadata.priority !== undefined && (typeof metadata.priority !== 'number' || metadata.priority < 0)) {
+      throw new Error('Health check priority must be a non-negative number');
+    }
+
+    if (metadata.dependencies && !Array.isArray(metadata.dependencies)) {
+      throw new Error('Health check dependencies must be an array');
+    }
+  }
+
+  /**
+   * Unregisters a health check from the registry.
+   * 
+   * @param {string} id - The ID of the health check to unregister
+   * @returns {boolean} True if the check was removed, false if it wasn't found
+   */
+  unregister(id) {
+    return this.checks.delete(id);
+  }
+
+  /**
+   * Gets metadata for a specific health check.
+   * 
+   * @param {string} id - The ID of the health check
+   * @returns {HealthCheckMetadata|undefined} The metadata or undefined if not found
+   */
+  get(id) {
+    return this.checks.get(id);
+  }
+
+  /**
+   * Gets all registered health check IDs.
+   * 
+   * @returns {string[]} Array of health check IDs
+   */
+  getAllIds() {
+    return Array.from(this.checks.keys());
+  }
+
+  /**
+   * Gets health checks filtered by category.
+   * 
+   * @param {string} category - The category to filter by
+   * @returns {HealthCheckMetadata[]} Array of health checks in the category
+   */
+  getByCategory(category) {
+    return Array.from(this.checks.values()).filter(check => check.category === category);
+  }
+
+  /**
+   * Gets all available categories.
+   * 
+   * @returns {string[]} Array of category names
+   */
+  getCategories() {
+    return Array.from(this.categories);
+  }
+
+  /**
+   * Checks if a health check is registered.
+   * 
+   * @param {string} id - The ID to check
+   * @returns {boolean} True if the check is registered
+   */
+  has(id) {
+    return this.checks.has(id);
+  }
+
+  /**
+   * Gets health checks sorted by priority and dependencies.
+   * 
+   * This method returns checks in an order that respects dependencies
+   * and priority settings, ensuring checks run in the correct sequence.
+   * 
+   * @param {string[]} [requestedIds] - Specific check IDs to include (optional)
+   * @returns {HealthCheckMetadata[]} Ordered array of health checks
+   */
+  getExecutionOrder(requestedIds) {
+    const availableChecks = requestedIds 
+      ? requestedIds.map(id => this.get(id)).filter(Boolean)
+      : Array.from(this.checks.values());
+
+    // Filter only enabled checks
+    const enabledChecks = availableChecks.filter(check => check.enabled);
+
+    // Sort by priority, then by ID for consistent ordering
+    return enabledChecks.sort((a, b) => {
+      if (a.priority !== b.priority) {
+        return a.priority - b.priority;
+      }
+      return a.id.localeCompare(b.id);
+    });
+  }
+
+  /**
+   * Executes a specific health check.
+   * 
+   * @param {string} id - The ID of the health check to execute
+   * @param {import('./providers.js').Provider} provider - The provider instance
+   * @returns {Promise<import('./health-check-utils.js').HealthCheckResult>} The check result
+   * @throws {Error} If the check is not registered or execution fails
+   */
+  async execute(id, provider) {
+    const metadata = this.get(id);
+    if (!metadata) {
+      throw new Error(`Health check '${id}' is not registered`);
+    }
+
+    if (!metadata.enabled) {
+      throw new Error(`Health check '${id}' is disabled`);
+    }
+
+    try {
+      const result = await metadata.checkFunction(provider);
+      
+      // Validate the result structure
+      if (!isValidHealthCheckResult(result)) {
+        throw new Error(`Health check '${id}' returned invalid result structure`);
+      }
+
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to execute health check '${id}': ${error.message}`);
+    }
+  }
+
+  /**
+   * Automatically discovers and registers health checks from the checks directory.
+   * 
+   * This method dynamically imports health check modules and registers them
+   * with the registry. It's designed to work with the standard module structure.
+   */
+  async autoDiscover() {
+    if (this.autoDiscovered) {
+      return; // Avoid duplicate discovery
+    }
+
+    try {
+      // Import the built-in health checks
+      const packageJsonModule = await import('./checks/package-json.js');
+      const specFilesModule = await import('./checks/spec-files.js');
+      const specsJsonModule = await import('./checks/specsjson.js');
+      const externalSpecsUrlsModule = await import('./checks/external-specs-urls.js');
+      const gitignoreModule = await import('./checks/gitignore.js');
+
+      // Register package.json check
+      if (packageJsonModule.checkPackageJson && packageJsonModule.CHECK_ID) {
+        this.register({
+          id: packageJsonModule.CHECK_ID,
+          name: packageJsonModule.CHECK_NAME || 'Package.json Check',
+          description: packageJsonModule.CHECK_DESCRIPTION || 'Validates package.json file',
+          checkFunction: packageJsonModule.checkPackageJson,
+          category: 'configuration',
+          priority: 10 // High priority for configuration checks
+        });
+      }
+
+      // Register spec files check
+      if (specFilesModule.checkSpecFiles && specFilesModule.CHECK_ID) {
+        this.register({
+          id: specFilesModule.CHECK_ID,
+          name: specFilesModule.CHECK_NAME || 'Specification Files Check',
+          description: specFilesModule.CHECK_DESCRIPTION || 'Discovers specification files',
+          checkFunction: specFilesModule.checkSpecFiles,
+          category: 'content',
+          priority: 20 // Lower priority, content checks can run after configuration
+        });
+      }
+
+      // Register specs.json check
+      if (specsJsonModule.checkSpecsJson && specsJsonModule.CHECK_ID) {
+        this.register({
+          id: specsJsonModule.CHECK_ID,
+          name: specsJsonModule.CHECK_NAME || 'Specs.json Check',
+          description: specsJsonModule.CHECK_DESCRIPTION || 'Validates specs.json file',
+          checkFunction: specsJsonModule.checkSpecsJson,
+          category: 'configuration',
+          priority: 15 // Between package-json and spec-files
+        });
+      }
+
+      // Register external specs URLs check
+      if (externalSpecsUrlsModule.checkExternalSpecsUrls && externalSpecsUrlsModule.CHECK_ID) {
+        this.register({
+          id: externalSpecsUrlsModule.CHECK_ID,
+          name: externalSpecsUrlsModule.CHECK_NAME || 'External Specs URL Validation',
+          description: externalSpecsUrlsModule.CHECK_DESCRIPTION || 'Validates external specification URLs',
+          checkFunction: externalSpecsUrlsModule.checkExternalSpecsUrls,
+          category: 'external-references',
+          priority: 30 // Run after specs.json is validated
+        });
+      }
+
+      // Register .gitignore check
+      if (gitignoreModule.checkGitignore && gitignoreModule.CHECK_ID) {
+        this.register({
+          id: gitignoreModule.CHECK_ID,
+          name: gitignoreModule.CHECK_NAME || '.gitignore Validation',
+          description: gitignoreModule.CHECK_DESCRIPTION || 'Validates .gitignore file',
+          checkFunction: gitignoreModule.checkGitignore,
+          category: 'configuration',
+          priority: 12 // After package.json, before specs.json
+        });
+      }
+
+      this.autoDiscovered = true;
+    } catch (error) {
+      console.warn('Failed to auto-discover some health checks:', error.message);
+    }
+  }
+
+  /**
+   * Gets a summary of the registry state.
+   * 
+   * @returns {Object} Summary information about registered checks
+   */
+  getSummary() {
+    const checks = Array.from(this.checks.values());
+    
+    return {
+      totalChecks: checks.length,
+      enabledChecks: checks.filter(c => c.enabled).length,
+      disabledChecks: checks.filter(c => !c.enabled).length,
+      categories: this.getCategories(),
+      checksByCategory: Object.fromEntries(
+        this.getCategories().map(cat => [cat, this.getByCategory(cat).length])
+      )
+    };
+  }
+
+  /**
+   * Enables or disables a health check.
+   * 
+   * @param {string} id - The ID of the health check
+   * @param {boolean} enabled - Whether to enable or disable the check
+   * @returns {boolean} True if the check was found and updated
+   */
+  setEnabled(id, enabled) {
+    const metadata = this.get(id);
+    if (metadata) {
+      metadata.enabled = enabled;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Clears all registered health checks.
+   * 
+   * This method is primarily useful for testing or when reinitializing
+   * the registry with a different set of checks.
+   */
+  clear() {
+    this.checks.clear();
+    this.categories.clear();
+    this.categories.add('general');
+    this.autoDiscovered = false;
+  }
+}
+
+/**
+ * Global registry instance for convenient access.
+ * Most applications should use this singleton instance.
+ * @type {HealthCheckRegistry}
+ */
+export const globalRegistry = new HealthCheckRegistry();
+
+/**
+ * Convenience function to register a health check with the global registry.
+ * 
+ * @param {HealthCheckMetadata} metadata - The health check metadata
+ */
+export function registerHealthCheck(metadata) {
+  globalRegistry.register(metadata);
+}
+
+/**
+ * Convenience function to get a health check from the global registry.
+ * 
+ * @param {string} id - The health check ID
+ * @returns {HealthCheckMetadata|undefined} The health check metadata
+ */
+export function getHealthCheck(id) {
+  return globalRegistry.get(id);
+}
+
+/**
+ * Convenience function to auto-discover health checks using the global registry.
+ */
+export async function autoDiscoverHealthChecks() {
+  await globalRegistry.autoDiscover();
+}

package/lib/health-check-utils.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Health check utilities and common types for spec-up-t-healthcheck
+ * 
+ * This module provides shared utilities, type definitions, and helper functions
+ * used across all health check modules. It ensures consistency in health check
+ * result formatting and provides a centralized location for common functionality.
+ * 
+ * @author spec-up-t-healthcheck
+ */
+
+/**
+ * @typedef {Object} HealthCheckResult
+ * @property {string} check - The name/identifier of the health check
+ * @property {'pass'|'fail'|'warn'|'skip'} status - The result status
+ * @property {string} message - Human-readable result message
+ * @property {string} timestamp - ISO timestamp when the check was performed
+ * @property {Object} [details={}] - Additional details about the check result
+ */
+
+/**
+ * @typedef {Object} HealthCheckSummary
+ * @property {number} total - Total number of checks performed
+ * @property {number} passed - Number of checks that passed
+ * @property {number} failed - Number of checks that failed
+ * @property {number} warnings - Number of checks with warnings
+ * @property {number} skipped - Number of checks that were skipped
+ * @property {number} score - Overall health score as a percentage (0-100)
+ * @property {boolean} hasErrors - Whether any checks failed
+ * @property {boolean} hasWarnings - Whether any checks had warnings
+ */
+
+/**
+ * @typedef {Object} HealthCheckReport
+ * @property {HealthCheckResult[]} results - Array of individual check results
+ * @property {HealthCheckSummary} summary - Aggregated summary of all check results
+ * @property {string} timestamp - ISO timestamp when the report was generated
+ * @property {Object} provider - Information about the provider used for checks
+ * @property {string} provider.type - The type of provider ('local', 'remote', etc.)
+ * @property {string} [provider.repoPath] - The repository path (for local providers)
+ */
+
+/**
+ * @typedef {function(import('./providers.js').Provider): Promise<HealthCheckResult>} HealthCheckFunction
+ * @description A function that performs a health check using a provider and returns a result
+ */
+
+/**
+ * Valid status values for health check results.
+ * @type {readonly string[]}
+ */
+export const HEALTH_CHECK_STATUSES = Object.freeze(['pass', 'fail', 'warn', 'skip']);
+
+/**
+ * Creates a standardized health check result object.
+ * 
+ * This utility function ensures consistent structure across all health check results,
+ * automatically adding timestamps and providing a standard format for reporting.
+ * The function validates input parameters to maintain data integrity.
+ * 
+ * @param {string} check - The identifier/name of the health check being performed
+ * @param {'pass'|'fail'|'warn'|'skip'} status - The status of the health check
+ * @param {string} message - A human-readable message describing the result
+ * @param {Object} [details={}] - Optional additional details about the check
+ * @returns {HealthCheckResult} A standardized health check result object
+ * @throws {Error} If check name or message is empty, or status is invalid
+ * 
+ * @example
+ * ```javascript
+ * const result = createHealthCheckResult(
+ *   'package-json',
+ *   'pass',
+ *   'package.json is valid',
+ *   { packageData: { name: 'my-spec', version: '1.0.0' } }
+ * );
+ * ```
+ */
+export function createHealthCheckResult(check, status, message, details = {}) {
+  // Input validation to ensure data integrity
+  if (typeof check !== 'string' || check.trim() === '') {
+    throw new Error('Check name must be a non-empty string');
+  }
+  
+  if (typeof message !== 'string' || message.trim() === '') {
+    throw new Error('Message must be a non-empty string');
+  }
+  
+  if (!HEALTH_CHECK_STATUSES.includes(status)) {
+    throw new Error(`Status must be one of: ${HEALTH_CHECK_STATUSES.join(', ')}`);
+  }
+  
+  if (details !== null && typeof details !== 'object') {
+    throw new Error('Details must be an object or null');
+  }
+
+  return {
+    check: check.trim(),
+    status,
+    message: message.trim(),
+    timestamp: new Date().toISOString(),
+    details: details || {}
+  };
+}
+
+/**
+ * Calculates summary statistics from an array of health check results.
+ * 
+ * This function aggregates individual health check results into a comprehensive
+ * summary that includes counts, percentages, and boolean flags for quick
+ * assessment of overall repository health.
+ * 
+ * @param {HealthCheckResult[]} results - Array of health check results to summarize
+ * @returns {HealthCheckSummary} Aggregated summary statistics
+ * 
+ * @example
+ * ```javascript
+ * const results = [
+ *   createHealthCheckResult('check1', 'pass', 'All good'),
+ *   createHealthCheckResult('check2', 'fail', 'Found issue')
+ * ];
+ * const summary = calculateSummary(results);
+ * console.log(summary.score); // 50 (50% passed)
+ * ```
+ */
+export function calculateSummary(results) {
+  if (!Array.isArray(results)) {
+    throw new Error('Results must be an array');
+  }
+
+  const summary = {
+    total: results.length,
+    passed: results.filter(r => r.status === 'pass').length,
+    failed: results.filter(r => r.status === 'fail').length,
+    warnings: results.filter(r => r.status === 'warn').length,
+    skipped: results.filter(r => r.status === 'skip').length
+  };
+
+  // Calculate health score as percentage of passed checks
+  summary.score = summary.total > 0 ? Math.round((summary.passed / summary.total) * 100) : 0;
+  
+  // Boolean flags for quick status assessment
+  summary.hasErrors = summary.failed > 0;
+  summary.hasWarnings = summary.warnings > 0;
+
+  return summary;
+}
+
+/**
+ * Validates that an object conforms to the HealthCheckResult interface.
+ * 
+ * This function performs runtime validation of health check result objects
+ * to ensure they meet the expected structure and data types. Useful for
+ * validating results from external or dynamic sources.
+ * 
+ * @param {any} result - The object to validate
+ * @returns {boolean} True if the object is a valid HealthCheckResult
+ * 
+ * @example
+ * ```javascript
+ * const result = { check: 'test', status: 'pass', message: 'OK', timestamp: '...' };
+ * if (isValidHealthCheckResult(result)) {
+ *   // Safe to use as HealthCheckResult
+ * }
+ * ```
+ */
+export function isValidHealthCheckResult(result) {
+  if (!result || typeof result !== 'object') {
+    return false;
+  }
+
+  const requiredFields = ['check', 'status', 'message', 'timestamp'];
+  
+  // Check all required fields are present and have correct types
+  for (const field of requiredFields) {
+    if (!(field in result) || typeof result[field] !== 'string') {
+      return false;
+    }
+  }
+
+  // Validate status is a known value
+  if (!HEALTH_CHECK_STATUSES.includes(result.status)) {
+    return false;
+  }
+
+  // Validate timestamp is a valid ISO string
+  if (isNaN(Date.parse(result.timestamp))) {
+    return false;
+  }
+
+  // Details field is optional but must be an object if present
+  if ('details' in result && (result.details === null || typeof result.details !== 'object')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Creates a standardized error result for health checks that encounter exceptions.
+ * 
+ * This utility function provides a consistent way to handle and report errors
+ * that occur during health check execution, ensuring proper error information
+ * is captured and formatted for reporting.
+ * 
+ * @param {string} check - The identifier of the health check that encountered an error
+ * @param {Error|string} error - The error object or error message
+ * @param {Object} [additionalDetails={}] - Additional context about the error
+ * @returns {HealthCheckResult} A standardized error result
+ * 
+ * @example
+ * ```javascript
+ * try {
+ *   // Health check logic
+ * } catch (error) {
+ *   return createErrorResult('my-check', error, { context: 'additional info' });
+ * }
+ * ```
+ */
+export function createErrorResult(check, error, additionalDetails = {}) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : undefined;
+  
+  const details = {
+    error: errorMessage,
+    ...(errorStack && { stack: errorStack }),
+    ...additionalDetails
+  };
+
+  return createHealthCheckResult(
+    check,
+    'fail',
+    `Error during health check: ${errorMessage}`,
+    details
+  );
+}