spec-up-t 1.2.7 → 1.2.9

package/src/health-check.js

@@ -1,5 +1,47 @@
 #!/usr/bin/env node
 
+/**
+ * @fileoverview Spec-Up-T Health Check Tool
+ * 
+ * This script performs comprehensive health checks on Spec-Up-T projects,
+ * validating configuration, external references, term definitions, and more.
+ * Generates an HTML report with detailed results and actionable feedback.
+ * 
+ * @author Spec-Up-T Team
+ * @version 1.0.0
+ * @since 2025-06-06
+ */
+
+/**
+ * @typedef {Object} HealthCheckResult
+ * @property {string} name - Name of the specific check
+ * @property {boolean|string} success - Success status (true, false, or 'partial')
+ * @property {string} [status] - Status override ('warning', 'pass', 'fail')
+ * @property {string} [details] - Additional details about the check result
+ */
+
+/**
+ * @typedef {Object} HealthCheckSection
+ * @property {string} title - Title of the check section
+ * @property {HealthCheckResult[]} results - Array of individual check results
+ */
+
+/**
+ * @typedef {Object} RepositoryInfo
+ * @property {string} host - Git hosting service (e.g., 'github')
+ * @property {string} account - Account/organization name
+ * @property {string} repo - Repository name
+ * @property {string} [branch] - Branch name
+ * @property {boolean} [verified] - Whether repository existence was verified
+ */
+
+/**
+ * @typedef {Object} StatusDisplay
+ * @property {string} statusClass - CSS class for styling
+ * @property {string} statusIcon - HTML icon element
+ * @property {string} statusText - Display text for status
+ */
+
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
@@ -13,7 +55,10 @@ const termsIntroChecker = require('./health-check/terms-intro-checker');
 const destinationGitignoreChecker = require('./health-check/destination-gitignore-checker');
 const trefTermChecker = require('./health-check/tref-term-checker');
 
-// Configuration
+/**
+ * Directory where health check reports are generated
+ * @constant {string}
+ */
 const OUTPUT_DIR = path.join(process.cwd(), '.cache');
 
 // Create output directory if it doesn't exist
@@ -21,7 +66,21 @@ if (!fs.existsSync(OUTPUT_DIR)) {
     fs.mkdirSync(OUTPUT_DIR, { recursive: true });
 }
 
-// Helper function to read specs.json file
+/**
+ * Retrieves repository information from specs.json file
+ * 
+ * Reads the specs.json file to extract repository configuration including
+ * host, account, repo name, and branch. Falls back to default values if
+ * the file doesn't exist or is missing required fields.
+ * 
+ * @async
+ * @function getRepoInfo
+ * @returns {Promise<RepositoryInfo>} Repository information object
+ * 
+ * @example
+ * const repoInfo = await getRepoInfo();
+ * console.log(repoInfo.account); // 'blockchain-bird'
+ */
 async function getRepoInfo() {
     try {
         // Path to the default boilerplate specs.json
@@ -132,7 +191,24 @@ async function getRepoInfo() {
     };
 }
 
-// Helper function to check if a repository exists
+/**
+ * Checks if a Git repository exists and is accessible
+ * 
+ * Makes an HTTP HEAD request to verify repository existence without
+ * downloading the full repository content. Handles timeouts and errors gracefully.
+ * 
+ * @function checkRepositoryExists
+ * @param {string} host - Git hosting service (e.g., 'github')
+ * @param {string} account - Account or organization name
+ * @param {string} repo - Repository name
+ * @returns {Promise<boolean>} True if repository exists and is accessible
+ * 
+ * @example
+ * const exists = await checkRepositoryExists('github', 'blockchain-bird', 'spec-up-t');
+ * if (exists) {
+ *   console.log('Repository is accessible');
+ * }
+ */
 function checkRepositoryExists(host, account, repo) {
     return new Promise((resolve) => {
         const url = `https://${host}.com/${account}/${repo}`;
@@ -163,7 +239,19 @@ function checkRepositoryExists(host, account, repo) {
     });
 }
 
-// Helper function to format current time for the filename
+/**
+ * Formats current timestamp for use in filenames
+ * 
+ * Generates a timestamp string that is safe to use in filenames by
+ * replacing special characters with hyphens. Format: YYYY-MM-DD-HH-mm-ssZ
+ * 
+ * @function getFormattedTimestamp
+ * @returns {string} Formatted timestamp string suitable for filenames
+ * 
+ * @example
+ * const timestamp = getFormattedTimestamp();
+ * console.log(timestamp); // "2025-06-06-14-30-25Z"
+ */
 function getFormattedTimestamp() {
     const now = new Date();
     return now.toISOString()
@@ -172,12 +260,37 @@ function getFormattedTimestamp() {
         .replace(/Z/g, 'Z');
 }
 
-// Helper function to generate a human-readable timestamp for display
+/**
+ * Generates a human-readable timestamp for display in reports
+ * 
+ * Creates a localized timestamp string for display purposes,
+ * using the system's default locale and timezone.
+ * 
+ * @function getHumanReadableTimestamp
+ * @returns {string} Human-readable timestamp string
+ * 
+ * @example
+ * const readable = getHumanReadableTimestamp();
+ * console.log(readable); // "6/6/2025, 2:30:25 PM"
+ */
 function getHumanReadableTimestamp() {
     return new Date().toLocaleString();
 }
 
-// Helper function to determine status display parameters based on result
+/**
+ * Determines status display parameters based on check result
+ * 
+ * Analyzes check results to determine appropriate CSS classes,
+ * icons, and text for visual status representation in the HTML report.
+ * 
+ * @function getStatusDisplay
+ * @param {HealthCheckResult} result - Check result object
+ * @returns {StatusDisplay} Status display configuration
+ * 
+ * @example
+ * const display = getStatusDisplay({ success: true });
+ * console.log(display.statusText); // "Pass"
+ */
 function getStatusDisplay(result) {
     if (result.status === 'warning' || result.success === 'partial') {
         // Warning status
@@ -203,7 +316,34 @@ function getStatusDisplay(result) {
     }
 }
 
-// Main function to run all checks and generate the report
+/**
+ * Main function to run all health checks and generate the report
+ * 
+ * Orchestrates the execution of all available health check modules,
+ * collects results, and generates a comprehensive HTML report.
+ * Handles errors gracefully and ensures proper cleanup.
+ * 
+ * @async
+ * @function runHealthCheck
+ * @throws {Error} When health check execution fails
+ * 
+ * @description
+ * The function performs the following checks:
+ * - Term reference checks in external specs
+ * - External specs URL validation
+ * - Term references validation
+ * - specs.json configuration validation
+ * - Terms introduction file validation
+ * - .gitignore destination directory check
+ * 
+ * @example
+ * try {
+ *   await runHealthCheck();
+ *   console.log('Health check completed successfully');
+ * } catch (error) {
+ *   console.error('Health check failed:', error);
+ * }
+ */
 async function runHealthCheck() {
     console.log('Running health checks...');
 
@@ -264,7 +404,27 @@ async function runHealthCheck() {
     }
 }
 
-// Generate HTML report
+/**
+ * Generates and opens an HTML health check report
+ * 
+ * Creates a comprehensive HTML report with all health check results,
+ * saves it to the cache directory, and opens it in the default browser.
+ * The report includes interactive features like filtering and status indicators.
+ * 
+ * @async
+ * @function generateReport
+ * @param {HealthCheckSection[]} checkResults - Array of health check result objects
+ * @throws {Error} When report generation or file operations fail
+ * 
+ * @example
+ * const results = [
+ *   {
+ *     title: 'Configuration Check',
+ *     results: [{ name: 'specs.json', success: true, details: 'Valid' }]
+ *   }
+ * ];
+ * await generateReport(results);
+ */
 async function generateReport(checkResults) {
     const timestamp = getFormattedTimestamp();
     // Get repository information from specs.json
@@ -289,7 +449,26 @@ async function generateReport(checkResults) {
     }
 }
 
-// Generate HTML content
+/**
+ * Generates HTML content for the health check report
+ * 
+ * Creates a complete HTML document with Bootstrap styling, interactive features,
+ * and comprehensive health check results. Includes repository verification,
+ * status filtering, and detailed result tables.
+ * 
+ * @function generateHtmlReport
+ * @param {HealthCheckSection[]} checkResults - Array of health check result sections
+ * @param {string} timestamp - Human-readable timestamp for the report
+ * @param {RepositoryInfo} repoInfo - Repository information object
+ * @returns {string} Complete HTML document as string
+ * 
+ * @example
+ * const html = generateHtmlReport(results, '6/6/2025, 2:30:25 PM', {
+ *   host: 'github',
+ *   account: 'blockchain-bird',
+ *   repo: 'spec-up-t'
+ * });
+ */
 function generateHtmlReport(checkResults, timestamp, repoInfo) {
     let resultsHtml = '';
 
@@ -457,5 +636,15 @@ function generateHtmlReport(checkResults, timestamp, repoInfo) {
   `;
 }
 
-// Run the health check
+/**
+ * Script execution entry point
+ * 
+ * Immediately executes the health check when this script is run directly.
+ * This allows the script to be used as a standalone command-line tool.
+ * 
+ * @example
+ * // Run from command line:
+ * // node src/health-check.js
+ * // npm run healthCheck
+ */
 runHealthCheck();

package/src/markdown-it-extensions.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { ESCAPED_PLACEHOLDER } = require('./escape-handler');
+
 /**
  * Configuration for custom template syntax [[example]] used throughout the markdown parsing
  * These constants define how template markers are identified and processed
@@ -64,6 +66,12 @@ module.exports = function (md, templates = {}) {
   md.inline.ruler.after('emphasis', 'templates', function templates_ruler(state, silent) {
     // Get the current parsing position
     var start = state.pos;
+    
+    // Check if we're at an escaped placeholder - if so, skip processing
+    if (state.src.slice(start, start + ESCAPED_PLACEHOLDER.length) === ESCAPED_PLACEHOLDER) {
+      return false;
+    }
+    
     // Check if we're at a template opening marker
     let prefix = state.src.slice(start, start + levels);
     if (prefix !== openString) return false;

package/src/collectExternalReferences/fetchTermsFromIndex.1.js

@@ -1,340 +0,0 @@
-/**
- * @file fetchTermsFromIndex.js
- * @description Fetches terms and definitions from external repository's index.html
- * @author Generated with assistance from GitHub Copilot
- * @version 1.0.0
- * @since 2025-04-15
- */
-
-const fs = require('fs');
-const path = require('path');
-const { JSDOM } = require('jsdom');
-const axios = require('axios');
-const { addPath, getPath, getAllPaths } = require('../../config/paths');
-const crypto = require('crypto');
-
-// Directory to store cached files
-const CACHE_DIR = getPath('githubcache');
-
-/**
- * Generates a cache key based on repository information
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name
- * @returns {string} - Cache key
- */
-function generateCacheKey(owner, repo) {
-    const input = `${owner}-${repo}-index`;
-    return crypto.createHash('md5').update(input).digest('hex');
-}
-
-/**
- * Checks if a cached version exists and is valid
- * @param {string} cacheKey - Cache key
- * @param {object} options - Options object
- * @param {number} options.cacheTTL - Time-to-live for cache in milliseconds (default: 24 hours)
- * @returns {object|null} - Cached data or null if not found or expired
- * @example
- * const cacheTTL = options.cacheTTL || 24 * 60 * 60 * 1000; // Default: 24 hours
- */
-function getFromCache(cacheKey, options = {}) {
-    const cachePath = path.join(CACHE_DIR, `${cacheKey}.json`);
-    // Use default 24h TTL instead of 0
-    const cacheTTL = options.cacheTTL || 24 * 60 * 60 * 1000;
-    
-    // Early return if file doesn't exist
-    if (!fs.existsSync(cachePath)) {
-        return null;
-    }
-    
-    // Try to read and parse the cache file
-    let cacheData;
-    try {
-        cacheData = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
-    } catch (error) {
-        console.log(`Error reading cache for key: ${cacheKey}`);
-        return null;
-    }
-    
-    // Check if cache has timestamp and is not expired
-    const cacheTime = new Date(cacheData.timestamp).getTime();
-    const currentTime = new Date().getTime();
-    const isExpired = currentTime - cacheTime > cacheTTL;
-    
-    if (isExpired) {
-        console.log(`Cache expired for key: ${cacheKey}`);
-        return null;
-    }
-    
-    console.log(`Using cached data for key: ${cacheKey}`);
-    return cacheData;
-}
-
-/**
- * Saves data to cache
- * @param {string} cacheKey - Cache key
- * @param {object} data - Data to cache
- */
-function saveToCache(cacheKey, data) {
-    const cachePath = path.join(CACHE_DIR, `${cacheKey}.json`);
-    const cacheData = {
-        timestamp: new Date().toISOString(),
-        ...data
-    };
-    fs.writeFileSync(cachePath, JSON.stringify(cacheData, null, 2));
-    console.log(`Saved to cache: ${cacheKey}`);
-}
-
-/**
- * Fetches the latest commit hash for a specific file in a repository
- * @param {string} token - GitHub API Token
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name
- * @param {string} filePath - Path to the file in the repository
- * @param {object} headers - Request headers
- * @returns {string|null} - Latest commit hash or null if error
- */
-async function getFileCommitHash(token, owner, repo, filePath, headers) {
-    try {
-        // Normalize the file path to ensure it doesn't have leading slash
-        const normalizedPath = filePath.replace(/^\//, '');
-        
-        // Construct API URL to get commits for the specific file
-        const commitsUrl = `https://api.github.com/repos/${owner}/${repo}/commits?path=${normalizedPath}&per_page=1`;
-        console.log(`Fetching latest commit for file: ${commitsUrl}`);
-        
-        const response = await axios.get(commitsUrl, { headers });
-        
-        if (response.status !== 200 || !response.data || response.data.length === 0) {
-            console.log(`❌ Could not find commit information for ${filePath}`);
-            return null;
-        }
-        
-        // Return the SHA of the latest commit
-        return response.data[0].sha;
-    } catch (error) {
-        console.error(`❌ Error fetching commit hash: ${error.message}`);
-        return null;
-    }
-}
-
-/**
- * Fetches all terms and definitions from a repository's index.html
- * @param {string} token - GitHub API Token
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name 
- * @param {object} options - Additional options
- * @returns {object|null} - Object containing all terms or null if error
- */
-async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
-    try {
-        // Generate cache key based on repo information
-        const cacheKey = generateCacheKey(owner, repo);
-        let cachedData = null;
-
-        // Check cache first if caching is enabled
-        if (options.cache !== false) {
-            cachedData = getFromCache(cacheKey, options);
-            if (cachedData) {
-                return cachedData;
-            }
-        }
-
-        // Configure headers for GitHub API
-        const headers = {};
-        if (token) {
-            headers['Authorization'] = `token ${token}`;
-        }
-
-        // Get the specs.json content from the repository to find the output_path
-        const specsJsonUrl = `https://api.github.com/repos/${owner}/${repo}/contents/specs.json`;
-        console.log(`Fetching specs.json from: ${specsJsonUrl}`);
-
-        // Fetch specs.json content
-        const specsJsonResponse = await axios.get(specsJsonUrl, { headers });
-        if (specsJsonResponse.status !== 200) {
-            console.log(`❌ Could not find specs.json in repository ${owner}/${repo}`);
-            return null;
-        }
-
-        // Decode specs.json content from base64
-        const specsJsonContent = Buffer.from(specsJsonResponse.data.content, 'base64').toString('utf8');
-        const specsJson = JSON.parse(specsJsonContent);
-        
-        // Get the output_path from specs.json
-        const outputPath = specsJson.specs[0].output_path;
-        if (!outputPath) {
-            console.log(`❌ No output_path found in specs.json for repository ${owner}/${repo}`);
-            return null;
-        }
-
-        // Fix: Properly normalize the output path to ensure it doesn't have leading "./" or trailing "/"
-        const normalizedOutputPath = outputPath.replace(/^\.\//, '').replace(/\/$/, '');
-        
-        // Create the path to the index.html file
-        const indexHtmlPath = `${normalizedOutputPath}/index.html`;
-        
-        // Fetch the index.html content with properly constructed URL
-        const indexHtmlUrl = `https://raw.githubusercontent.com/${owner}/${repo}/main/${indexHtmlPath}`;
-        console.log(`Fetching index.html from: ${indexHtmlUrl}`);
-        
-        const indexHtmlResponse = await axios.get(indexHtmlUrl, { headers });
-        if (indexHtmlResponse.status !== 200) {
-            console.log(`❌ Could not find index.html at ${indexHtmlUrl}`);
-            return null;
-        }
-
-        // Get the commit hash for the index.html file
-        const commitHash = await getFileCommitHash(token, owner, repo, indexHtmlPath, headers);
-        if (!commitHash) {
-            console.log(`⚠️ Could not get commit hash for index.html, continuing without it`);
-        }
-
-        const htmlContent = indexHtmlResponse.data;
-        
-        // Parse HTML using JSDOM
-        const dom = new JSDOM(htmlContent);
-        const document = dom.window.document;
-        
-        // Find all term definition lists with class "terms-and-definitions-list"
-        const termDlList = document.querySelector('dl.terms-and-definitions-list');
-        if (!termDlList) {
-            console.log(`❌ No terms-and-definitions-list found in ${indexHtmlUrl}`);
-            return null;
-        }
-
-        // Extract all terms and definitions
-        const terms = [];
-        let dtElements = termDlList.querySelectorAll('dt');
-        
-        dtElements.forEach(dt => {
-            // Find the term span that starts with id="term:
-            const termSpan = dt.querySelector('span[id^="term:"]');
-            if (!termSpan) return;
-
-            // Get the term text (all text content, excluding nested spans)
-            let termText = '';
-            for (let node of termSpan.childNodes) {
-                if (node.nodeType === dom.window.Node.TEXT_NODE) {
-                    termText += node.textContent.trim();
-                }
-            }
-            
-            // If no text found, try to get the full text content
-            if (!termText) {
-                termText = termSpan.textContent.trim();
-            }
-            
-            // Skip empty terms
-            if (!termText) return;
-            
-            // Find all corresponding definition elements
-            let dds = [];
-            let nextElement = dt.nextElementSibling;
-            
-            // Collect all consecutive <dd> elements until we reach another <dt>
-            while (nextElement && nextElement.tagName.toLowerCase() === 'dd') {
-                dds.push(nextElement.outerHTML);
-                nextElement = nextElement.nextElementSibling;
-            }
-            
-            terms.push({
-                term: termText,
-                definition: dds.join('\n')
-            });
-        });
-
-        // Store all terms in a JSON file with timestamp
-        const timestamp = Date.now();
-        const outputDir = path.join(CACHE_DIR);
-        if (!fs.existsSync(outputDir)) {
-            fs.mkdirSync(outputDir, { recursive: true });
-        }
-        
-        // Create output filename with timestamp
-        const outputFileName = `${timestamp}-${owner}-${repo}-terms.json`;
-        const outputFilePath = path.join(outputDir, outputFileName);
-        
-        // Create the result object
-        const result = {
-            timestamp,
-            repository: `${owner}/${repo}`,
-            terms,
-            sha: commitHash, // Use the commit hash of the index.html file
-            avatarUrl: null,
-            outputFileName
-        };
-        
-        // Save all terms to file
-        fs.writeFileSync(outputFilePath, JSON.stringify(result, null, 2));
-        console.log(`✅ Saved ${terms.length} terms to ${outputFilePath}`);
-        
-        // Save to cache if enabled
-        if (options.cache !== false) {
-            saveToCache(cacheKey, result);
-        }
-        
-        return result;
-
-    } catch (error) {
-        if (error.response) {
-            if (error.response.status === 404) {
-                console.log(`❌ Resource not found: ${error.config.url}`);
-            } else if (error.response.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') {
-                const resetTime = new Date(parseInt(error.response.headers['x-ratelimit-reset']) * 1000);
-                console.error(`❌ GitHub API rate limit exceeded. Try again after ${resetTime.toLocaleString()}`);
-            } else {
-                console.error(`❌ Error fetching data: ${error.response.status} ${error.response.statusText}`);
-            }
-        } else {
-            console.error(`❌ Error fetching term: ${error.message}`);
-        }
-        return null;
-    }
-}
-
-/**
- * Fetches a specific term from repository's index.html
- * This is a wrapper that uses fetchAllTermsFromIndex for efficiency
- * @param {string} token - GitHub API Token
- * @param {string} term - The specific term to look for
- * @param {string} owner - Repository owner
- * @param {string} repo - Repository name
- * @param {string} termsDir - Directory containing term definitions (not used in this implementation)
- * @param {object} options - Additional options
- * @returns {object|null} - Found term data or null if not found
- */
-async function fetchTermsFromIndex(token, term, owner, repo, termsDir, options = {}) {
-    // First get all terms from the repository (which is cached)
-    const allTermsData = await fetchAllTermsFromIndex(token, owner, repo, options);
-    
-    if (!allTermsData || !allTermsData.terms) {
-        return null;
-    }
-    
-    // Find the specific term
-    const foundTerm = allTermsData.terms.find(t => t.term.toLowerCase() === term.toLowerCase());
-    
-    if (foundTerm) {
-        console.log(`Found term '${term}' in repository ${owner}/${repo}`);
-        return {
-            term: foundTerm.term,
-            content: foundTerm.definition,
-            sha: allTermsData.sha,
-            repository: {
-                owner: {
-                    login: owner,
-                    avatar_url: allTermsData.avatarUrl
-                },
-                name: repo
-            }
-        };
-    } else {
-        console.log(`❌ Term "${term}" not found in repository ${owner}/${repo}`);
-        return null;
-    }
-}
-
-module.exports = {
-    fetchTermsFromIndex,
-    fetchAllTermsFromIndex  // Export the function to fetch all terms as well
-};