spec-up-t-healthcheck 1.0.0 → 1.1.0

package/README.md

@@ -138,6 +138,11 @@ The HTML format generates beautiful, interactive reports with:
 
 - **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.
 

package/lib/checks/console-messages.js

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Health check for console messages captured during spec-up-t operations
+ * 
+ * This check reads the `.cache/console-messages.json` file generated by spec-up-t's
+ * message collector during menu operations [1] (render) and [4] (collect external references).
+ * It analyzes the captured messages for errors, warnings, and other issues.
+ * 
+ * The check provides insights into:
+ * - Errors that occurred during operations
+ * - Warnings that may indicate potential issues
+ * - Operation success rate
+ * - Message statistics and patterns
+ * 
+ * @module checks/console-messages
+ */
+
+/**
+ * Analyzes console messages captured from spec-up-t operations
+ * 
+ * This function reads the console messages JSON file and provides detailed
+ * analysis of any errors, warnings, or issues found during render or
+ * external reference collection operations.
+ * 
+ * @param {Object} provider - File system provider for accessing project files
+ * @param {Object} [options={}] - Check options
+ * @param {boolean} [options.verbose=false] - Include all messages in details
+ * @returns {Promise<Object>} Health check result with console message analysis
+ * 
+ * @example
+ * const result = await checkConsoleMessages(provider);
+ * console.log(`Status: ${result.status}`);
+ * console.log(`Errors found: ${result.details.errorCount}`);
+ */
+export async function checkConsoleMessages(provider, options = {}) {
+    const checkName = 'console-messages';
+    const messagePath = '.cache/console-messages.json';
+    
+    try {
+        // Check if the console messages file exists
+        const fileExists = await provider.fileExists(messagePath);
+        
+        if (!fileExists) {
+            return {
+                check: checkName,
+                status: 'skip',
+                message: 'Console messages file not found. Run "npm run render" or "npm run collectExternalReferences" to generate it.',
+                timestamp: new Date().toISOString(),
+                details: {
+                    path: messagePath,
+                    fileExists: false,
+                    suggestion: 'Console message collection is available after running menu operations [1] or [4].'
+                }
+            };
+        }
+        
+        // Read and parse the console messages file
+        const content = await provider.readFile(messagePath);
+        let consoleData;
+        
+        try {
+            consoleData = JSON.parse(content);
+        } catch (parseError) {
+            return {
+                check: checkName,
+                status: 'fail',
+                message: 'Failed to parse console messages file',
+                timestamp: new Date().toISOString(),
+                details: {
+                    path: messagePath,
+                    error: parseError.message,
+                    fileExists: true
+                }
+            };
+        }
+        
+        // Extract metadata and messages
+        const metadata = consoleData.metadata || {};
+        const messages = consoleData.messages || [];
+        
+        // Analyze messages by type
+        const errorMessages = messages.filter(m => m.type === 'error');
+        const warningMessages = messages.filter(m => m.type === 'warn');
+        const successMessages = messages.filter(m => m.type === 'success');
+        
+        // Determine status based on message analysis
+        let status;
+        let message;
+        
+        if (errorMessages.length > 0) {
+            status = 'fail';
+            message = `Found ${errorMessages.length} error(s) in console output`;
+        } else if (warningMessages.length > 0) {
+            status = 'warn';
+            message = `Found ${warningMessages.length} warning(s) in console output`;
+        } else if (messages.length === 0) {
+            status = 'skip';
+            message = 'No console messages captured (file is empty)';
+        } else {
+            status = 'pass';
+            message = `Console output looks healthy (${successMessages.length} successful operations)`;
+        }
+        
+        // Build detailed information
+        const details = {
+            path: messagePath,
+            fileExists: true,
+            metadata: {
+                generatedAt: metadata.generatedAt,
+                totalMessages: metadata.totalMessages || 0,
+                operations: metadata.operations || [],
+                messagesByType: metadata.messagesByType || {}
+            },
+            analysis: {
+                errorCount: errorMessages.length,
+                warningCount: warningMessages.length,
+                successCount: successMessages.length,
+                totalMessages: messages.length
+            },
+            // Include ALL errors (no truncation)
+            errors: errorMessages.map(m => ({
+                timestamp: m.timestamp,
+                message: m.message,
+                operation: m.operation,
+                additionalData: m.additionalData
+            })),
+            warnings: warningMessages.slice(0, 10).map(m => ({
+                timestamp: m.timestamp,
+                message: m.message,
+                operation: m.operation,
+                additionalData: m.additionalData
+            }))
+        };
+        
+        // Include all messages for display in HTML report
+        // This allows users to see the complete console output in a table format
+        // Always include all messages (regardless of status) so users can see full context
+        details.allMessages = messages;
+        
+        // Add truncation notice only for warnings (errors are never truncated)
+        if (warningMessages.length > 10) {
+            details.warningsNote = `Showing first 10 of ${warningMessages.length} warnings`;
+        }
+        
+        return {
+            check: checkName,
+            status,
+            message,
+            timestamp: new Date().toISOString(),
+            details
+        };
+        
+    } catch (error) {
+        return {
+            check: checkName,
+            status: 'fail',
+            message: `Failed to check console messages: ${error.message}`,
+            timestamp: new Date().toISOString(),
+            details: {
+                path: messagePath,
+                error: error.message,
+                stack: error.stack
+            }
+        };
+    }
+}
+
+/**
+ * Get statistics from console messages without performing a full check
+ * 
+ * This is a utility function for quickly accessing message statistics
+ * without running the full health check.
+ * 
+ * @param {Object} provider - File system provider
+ * @returns {Promise<Object|null>} Statistics object or null if file doesn't exist
+ */
+export async function getConsoleMessageStats(provider) {
+    const messagePath = '.cache/console-messages.json';
+    
+    try {
+        const fileExists = await provider.fileExists(messagePath);
+        if (!fileExists) {
+            return null;
+        }
+        
+        const content = await provider.readFile(messagePath);
+        const consoleData = JSON.parse(content);
+        const messages = consoleData.messages || [];
+        
+        return {
+            total: messages.length,
+            errors: messages.filter(m => m.type === 'error').length,
+            warnings: messages.filter(m => m.type === 'warn').length,
+            successes: messages.filter(m => m.type === 'success').length,
+            operations: [...new Set(messages.map(m => m.operation).filter(Boolean))],
+            generatedAt: consoleData.metadata?.generatedAt
+        };
+    } catch (error) {
+        return null;
+    }
+}
+
+/**
+ * Check metadata for this health check
+ */
+export const checkConsoleMessagesMetadata = {
+    id: 'console-messages',
+    name: 'Console Messages',
+    description: 'Analyzes console output captured during spec-up-t operations',
+    category: 'operations',
+    tags: ['console', 'messages', 'errors', 'warnings', 'operations']
+};

package/lib/checks/external-specs-urls.js

@@ -42,6 +42,22 @@ const HTTP_TIMEOUT = 10000;
  */
 const MAX_REDIRECTS = 5;
 
+/**
+ * Proxy URL for browser environments (to bypass CORS)
+ * Assumes proxy.php is in the public root directory
+ * @type {string}
+ */
+const PROXY_URL = './proxy.php';
+
+/**
+ * Detects if code is running in a browser environment
+ * 
+ * @returns {boolean} True if running in browser
+ */
+function isBrowserEnvironment() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
 /**
  * Validates that a string is a properly formatted URL
  * 
@@ -181,6 +197,8 @@ async function checkUrlAccessibility(url, fieldName) {
 
 /**
  * Attempts to check URL accessibility using HEAD request
+ * In browser environments, attempts to use proxy to bypass CORS restrictions.
+ * Falls back gracefully if proxy is unavailable (e.g., in dev environment).
  * 
  * @param {string} url - The URL to check
  * @param {string} fieldName - Name of the field being checked
@@ -188,13 +206,31 @@ async function checkUrlAccessibility(url, fieldName) {
  */
 async function attemptHeadRequest(url, fieldName) {
     try {
-        const response = await axios.head(url, {
-            timeout: HTTP_TIMEOUT,
-            maxRedirects: MAX_REDIRECTS,
-            validateStatus: (status) => status < 500
-        });
-
-        return createAccessibilityResult(response.status, fieldName);
+        const isBrowser = isBrowserEnvironment();
+        
+        if (isBrowser) {
+            // In browser, try using proxy first
+            try {
+                const proxyUrl = `${PROXY_URL}?url=${encodeURIComponent(url)}`;
+                const response = await axios.head(proxyUrl, {
+                    timeout: HTTP_TIMEOUT,
+                    validateStatus: (status) => status < 500
+                });
+                return createAccessibilityResult(response.status, fieldName);
+            } catch (proxyError) {
+                // Proxy not available (e.g., dev environment without PHP)
+                // Return null to skip this check gracefully
+                return null;
+            }
+        } else {
+            // In Node.js, make direct request
+            const response = await axios.head(url, {
+                timeout: HTTP_TIMEOUT,
+                maxRedirects: MAX_REDIRECTS,
+                validateStatus: (status) => status < 500
+            });
+            return createAccessibilityResult(response.status, fieldName);
+        }
     } catch (error) {
         // Return null to signal that GET should be attempted
         return null;
@@ -203,6 +239,8 @@ async function attemptHeadRequest(url, fieldName) {
 
 /**
  * Attempts to check URL accessibility using GET request
+ * In browser environments, attempts to use proxy to bypass CORS restrictions.
+ * Falls back gracefully if proxy is unavailable (e.g., in dev environment).
  * 
  * @param {string} url - The URL to check
  * @param {string} fieldName - Name of the field being checked
@@ -210,13 +248,33 @@ async function attemptHeadRequest(url, fieldName) {
  */
 async function attemptGetRequest(url, fieldName) {
     try {
-        const response = await axios.get(url, {
-            timeout: HTTP_TIMEOUT,
-            maxRedirects: MAX_REDIRECTS,
-            validateStatus: (status) => status < 500
-        });
-
-        return createAccessibilityResult(response.status, fieldName);
+        const isBrowser = isBrowserEnvironment();
+        
+        if (isBrowser) {
+            // In browser, try using proxy
+            try {
+                const proxyUrl = `${PROXY_URL}?url=${encodeURIComponent(url)}`;
+                const response = await axios.get(proxyUrl, {
+                    timeout: HTTP_TIMEOUT,
+                    validateStatus: (status) => status < 500
+                });
+                return createAccessibilityResult(response.status, fieldName);
+            } catch (proxyError) {
+                // Proxy not available (e.g., dev environment without PHP)
+                return {
+                    isAccessible: false,
+                    message: `${fieldName} accessibility check skipped (proxy unavailable in dev environment)`
+                };
+            }
+        } else {
+            // In Node.js, make direct request
+            const response = await axios.get(url, {
+                timeout: HTTP_TIMEOUT,
+                maxRedirects: MAX_REDIRECTS,
+                validateStatus: (status) => status < 500
+            });
+            return createAccessibilityResult(response.status, fieldName);
+        }
     } catch (error) {
         return {
             isAccessible: false,
@@ -261,6 +319,7 @@ async function validateExternalSpec(spec, index, checkAccessibility = true) {
         specId: spec.external_spec || `[spec ${index}]`,
         errors: [],
         warnings: [],
+        info: [],
         success: []
     };
 
@@ -280,7 +339,7 @@ async function validateExternalSpec(spec, index, checkAccessibility = true) {
             results.success.push('Field "gh_page" has valid URL structure');
 
             if (ghPageStructure.message) {
-                results.warnings.push(ghPageStructure.message);
+                results.info.push(ghPageStructure.message);
             }
 
             // Check gh_page accessibility
@@ -336,6 +395,9 @@ async function validateExternalSpec(spec, index, checkAccessibility = true) {
  * 5. Validates url structure (proper format for GitHub repository)
  * 6. Checks if url is accessible (returns HTTP 200)
  *
+ * Note: In browser environments, accessibility checks use a proxy (/proxy.php)
+ * to bypass CORS restrictions. The proxy must be available for full validation.
+ *
  * @param {import('../providers.js').Provider} provider - The provider instance for file operations
  * @param {Object} options - Validation options
  * @param {boolean} options.checkAccessibility - Whether to check URL accessibility (default: true)
@@ -349,7 +411,10 @@ async function validateExternalSpec(spec, index, checkAccessibility = true) {
  * ```
  */
 export async function checkExternalSpecsUrls(provider, options = {}) {
-    const { checkAccessibility = true } = options;
+    // Default to checking accessibility (proxy handles CORS in browser)
+    const checkAccessibility = options.checkAccessibility !== undefined 
+        ? options.checkAccessibility 
+        : true;
 
     try {
         // Check if specs.json exists
@@ -432,6 +497,7 @@ export async function checkExternalSpecsUrls(provider, options = {}) {
         const allResults = [];
         const totalErrors = [];
         const totalWarnings = [];
+        const totalInfo = [];
         const totalSuccess = [];
 
         for (let i = 0; i < spec.external_specs.length; i++) {
@@ -441,6 +507,7 @@ export async function checkExternalSpecsUrls(provider, options = {}) {
 
             totalErrors.push(...result.errors.map(err => `${result.specId}: ${err}`));
             totalWarnings.push(...result.warnings.map(warn => `${result.specId}: ${warn}`));
+            totalInfo.push(...result.info.map(inf => `${result.specId}: ${inf}`));
             totalSuccess.push(...result.success.map(succ => `${result.specId}: ${succ}`));
         }
 
@@ -454,6 +521,15 @@ export async function checkExternalSpecsUrls(provider, options = {}) {
         } else if (totalWarnings.length > 0) {
             status = 'warn';
             message = `External specs validated with ${totalWarnings.length} warning(s)`;
+        } else if (totalInfo.length > 0) {
+            // Info messages don't affect the pass status
+            message = `All ${spec.external_specs.length} external spec(s) validated successfully (${totalInfo.length} info note(s))`;
+        }
+
+        // Collect all informational messages
+        const infoMessages = [...totalInfo];
+        if (isBrowserEnvironment() && checkAccessibility) {
+            infoMessages.push('URL accessibility checks performed via proxy (browser environment)');
         }
 
         return createHealthCheckResult(
@@ -465,6 +541,7 @@ export async function checkExternalSpecsUrls(provider, options = {}) {
                 errors: totalErrors,
                 warnings: totalWarnings,
                 success: totalSuccess,
+                info: infoMessages.length > 0 ? infoMessages : undefined,
                 detailedResults: allResults,
                 accessibilityChecked: checkAccessibility
             }

package/lib/checks/gitignore.js

@@ -25,7 +25,7 @@ export const CHECK_ID = 'gitignore';
  * Human-readable name for this health check.
  * @type {string}
  */
-export const CHECK_NAME = '.gitignore Validation';
+export const CHECK_NAME = '.gitignore';
 
 /**
  * Description of what this health check validates.