spec-up-t 1.2.7 → 1.2.8

package/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+- All code will have to pass SonarQube analysis
+- Cognitive complexity should be kept ideally below 15
+- Remove code if possible, instead of adding code

package/index.js

@@ -35,6 +35,7 @@ module.exports = async function (options = {}) {
     createVersionsIndex(config.specs[0].output_path);
 
     const { fixMarkdownFiles } = require('./src/fix-markdown-files.js');
+    const { processEscapedTags, restoreEscapedTags } = require('./src/escape-mechanism.js');
 
     let template = fs.readFileSync(path.join(modulePath, 'templates/template.html'), 'utf8');
     let assets = fs.readJsonSync(modulePath + '/config/asset-map.json');
@@ -528,7 +529,12 @@ module.exports = async function (options = {}) {
 
         let doc = docs.join("\n");
 
-        // `doc` is markdown 
+        // Handles backslash escape mechanism for substitution tags
+        // Phase 1: Pre-processing - Handle escaped tags
+        doc = processEscapedTags(doc);
+
+        // Handles backslash escape mechanism for substitution tags
+        // Phase 2: Tag Processing - Apply normal substitution logic
         doc = applyReplacers(doc);
 
         md[spec.katex ? "enable" : "disable"](katexRules);
@@ -542,6 +548,10 @@ module.exports = async function (options = {}) {
         // Sort definition terms case-insensitively before final rendering
         renderedHtml = sortDefinitionTermsInHtml(renderedHtml);
 
+        // Handles backslash escape mechanism for substitution tags
+        // Phase 3: Post-processing - Restore escaped sequences as literals
+        renderedHtml = restoreEscapedTags(renderedHtml);
+
         // Process external references to ensure they are inserted as raw HTML, not as JSON string
         const externalReferencesHtml = Array.isArray(externalReferences) 
           ? externalReferences.join('') 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {

package/src/collect-external-references.js

@@ -270,13 +270,17 @@ function processExternalReferences(config, GITHUB_API_TOKEN, options) {
  * 
  * @description
  * This function performs several key operations:
- * 1. Validates GitHub PAT availability and external repository configurations
+ * 1. Optionally uses GitHub PAT for better API performance and higher rate limits
  * 2. Checks validity of repository URLs
  * 3. Extracts xref/tref patterns from markdown content
  * 4. Extends references with repository metadata
  * 5. Processes references to fetch commit information
  * 6. Generates output files in both JS and JSON formats
  * 
+ * Note: The function will run without a GitHub token but may encounter rate limits.
+ * For better performance, provide a GitHub Personal Access Token via environment
+ * variable or the options parameter.
+ * 
  * @example
  * // Basic usage
  * collectExternalReferences();
@@ -289,17 +293,6 @@ function collectExternalReferences(options = {}) {
     const externalSpecsRepos = config.specs[0].external_specs;
     const GITHUB_API_TOKEN = options.pat || process.env.GITHUB_API_TOKEN;
 
-    const explanationPAT =
-`❌ No GitHub Personal Access Token (PAT) was found.
-
-   GitHub requires you to set up a PAT to retrieve external references.
-
-   There is no point in continuing without a PAT, so we stop here.
-
-   Find instructions on how to get a PAT at https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token
-
- `;
-
     const explanationNoExternalReferences =
 `❌ No external references were found in the specs.json file.
 
@@ -310,19 +303,13 @@ function collectExternalReferences(options = {}) {
 `;
     
     // First do some checks
-
-    // Do not run the script if the GitHub API token is not set
+    // Show informational message if no token is available
     if (!GITHUB_API_TOKEN) {
-        console.log(explanationPAT);
-        const userInput = readlineSync.question('ℹ️ Press any key');
-
-        // React to user pressing any key
-        if (userInput.trim() !== '') {
-            console.log('ℹ️ Stopping...');
-            return;
-        }
+        console.log('ℹ️ No GitHub Personal Access Token (PAT) found. Running without authentication (may hit rate limits).');
+        console.log('💡 For better performance, set up a PAT: https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token\n');
     }
-    else if (externalSpecsRepos.length === 0) {
+
+    if (externalSpecsRepos.length === 0) {
         // Check if the URLs for the external specs repositories are valid, and prompt the user to abort if they are not.
         console.log(explanationNoExternalReferences);
         const userInput = readlineSync.question('Press any key');

package/src/escape-mechanism.js

@@ -0,0 +1,57 @@
+/**
+ * Escape Mechanism Module for Spec-Up Substitution Tags
+ * 
+ * This module provides functions to handle backslash escape sequences for substitution tags,
+ * allowing users to display tag syntax literally in their documentation.
+ * 
+ * The escape mechanism works in three phases:
+ * 1. Pre-processing: Convert escaped sequences to temporary placeholders
+ * 2. Tag processing: Normal substitution logic (handled elsewhere)
+ * 3. Post-processing: Restore escaped sequences as literals
+ * 
+ * Supported escape pattern:
+ * - \[[tag: content]] → displays as literal [[tag: content]]
+ * 
+ * @version 1.0.0
+ */
+
+/**
+ * Handles backslash escape mechanism for substitution tags
+ * 
+ * Use backslash escape sequences to allow literal [[ tags in markdown
+ * 
+ * Phase 1: Pre-processing - Convert escaped sequences to temporary placeholders
+ * 
+ * @param {string} doc - The markdown document to process
+ * @returns {string} - Document with escaped sequences converted to placeholders
+ */
+function processEscapedTags(doc) {
+  // Replace \[[ with escape placeholder for literal display
+  // In markdown: \[[def: term]] should become [[def: term]] (literal tag syntax)
+  doc = doc.replace(/\\(\[\[)/g, '__SPEC_UP_ESCAPED_TAG__');
+  
+  return doc;
+}
+
+/**
+ * Handles backslash escape mechanism for substitution tags
+ * 
+ * Use backslash escape sequences to allow literal [[ tags in markdown
+ * 
+ * Phase 3: Post-processing - Restore escaped sequences as literals
+ * Converts placeholders back to literal [[ characters
+ * 
+ * @param {string} renderedHtml - The rendered HTML to process
+ * @returns {string} - HTML with placeholders restored to literal [[ tags
+ */
+function restoreEscapedTags(renderedHtml) {
+  // Replace escaped tag placeholders with literal [[ 
+  renderedHtml = renderedHtml.replace(/__SPEC_UP_ESCAPED_TAG__/g, '[[');
+  
+  return renderedHtml;
+}
+
+module.exports = {
+  processEscapedTags,
+  restoreEscapedTags
+};

package/src/health-check/specs-configuration-checker.js

@@ -1,3 +1,32 @@
+/**
+ * @fileoverview Spec-Up-T specs.json Configuration Validator
+ * 
+ * Validates specs.json configuration files by comparing project configurations
+ * against default templates to ensure proper setup and catch common issues.
+ * 
+ * **Validation Flow:**
+ * 1. File existence check (project specs.json + default template)
+ * 2. Field categorization (required vs optional fields)
+ * 3. Required field validation (presence + configuration status)
+ * 4. Optional field validation (configuration warnings)
+ * 5. Unexpected field detection (typo prevention)
+ * 6. Summary report generation
+ * 
+ * **Field Categories:**
+ * - **Required fields**: Must be present (e.g., title, author, source)
+ * - **Optional fields**: Can be omitted (e.g., logo, external_specs)
+ * - **Must-change fields**: Cannot use default values (title, author, etc.)
+ * - **Allow-default fields**: Can keep default values (spec_directory, etc.)
+ * - **Deprecated fields**: Legacy fields ignored during validation
+ * 
+ * **Output:**
+ * Returns structured validation results with pass/fail/warning status,
+ * detailed messages, and actionable feedback for configuration improvements.
+ * 
+ * @author Spec-Up-T Team
+ * @since 2025-06-06
+ */
+
 const fs = require('fs');
 const path = require('path');
 
@@ -51,9 +80,18 @@ const knownOptionalFields = [
     'external_specs',
     'logo_link',
     'favicon',
-    'katex'
+    'katex',
+    'spec_directory',
+    'spec_terms_directory',
+    'output_path',
+    'markdown_paths'
 ];
 
+/**
+ * Deprecated fields that should not be flagged as unexpected
+ */
+const deprecatedFields = [];
+
 /**
  * Check if the files needed for configuration check exist
  * @param {string} projectSpecsPath - Path to project specs.json
@@ -80,32 +118,87 @@ function checkFilesExist(projectSpecsPath, defaultSpecsPath) {
     return null;
 }
 
+/**
+ * Get all valid field names (required + optional + deprecated). Creates a comprehensive list of all field names that should not be flagged as "unexpected"
+ * @param {Array} defaultSpecKeys - Keys from default specs
+ * @returns {Array} - All valid field names
+ */
+function getAllValidFields(defaultSpecKeys) {
+    // Get all field names from descriptions (these are the canonical field names)
+    const canonicalFields = Object.keys(fieldDescriptions);
+    
+    // Combine with known optional fields and deprecated fields
+    const allValidFields = [
+        ...canonicalFields,
+        ...knownOptionalFields,
+        ...deprecatedFields,
+        ...defaultSpecKeys
+    ];
+    
+    // Remove duplicates
+    return [...new Set(allValidFields)];
+}
+
 /**
  * Categorize fields into required and optional
  * @param {Array} defaultSpecKeys - Keys from default specs
  * @returns {Object} - Object containing required and optional fields
  */
 function categorizeFields(defaultSpecKeys) {
+    const createFieldObject = key => ({
+        key,
+        description: fieldDescriptions[key] || `${key.replace(/_/g, ' ')} field`,
+        allowDefaultValue: allowDefaultValueFields.includes(key),
+        mustChange: mustChangeFields.includes(key)
+    });
+
     const requiredFields = defaultSpecKeys
         .filter(key => !knownOptionalFields.includes(key))
-        .map(key => ({
-            key,
-            description: fieldDescriptions[key] || `${key.replace(/_/g, ' ')} field`,
-            allowDefaultValue: allowDefaultValueFields.includes(key),
-            mustChange: mustChangeFields.includes(key)
-        }));
+        .map(createFieldObject);
 
     const optionalFields = defaultSpecKeys
         .filter(key => knownOptionalFields.includes(key))
-        .map(key => ({
-            key,
-            description: fieldDescriptions[key] || `${key.replace(/_/g, ' ')} field`,
-            allowDefaultValue: allowDefaultValueFields.includes(key)
-        }));
+        .map(createFieldObject);
 
     return { requiredFields, optionalFields };
 }
 
+/**
+ * Process field validation results. Orchestrates the validation of all fields in the specs.json
+ * @param {Object} projectSpecs - Project specs object  
+ * @param {Object} defaultSpecs - Default specs object
+ * @param {Array} defaultSpecKeys - Keys from default specs
+ * @returns {Object} - Object with results and missingRequiredKeys
+ */
+function processFieldValidation(projectSpecs, defaultSpecs, defaultSpecKeys) {
+    const { requiredFields, optionalFields } = categorizeFields(defaultSpecKeys);
+    
+    const requiredResults = requiredFields.map(field => evaluateRequiredField(field, projectSpecs, defaultSpecs));
+    const optionalResults = optionalFields.map(field => evaluateOptionalField(field, projectSpecs, defaultSpecs));
+    
+    const missingRequiredKeys = requiredResults
+        .filter(result => !result.success && result.details.includes('missing'))
+        .map((_, index) => requiredFields[index].key);
+    
+    return { 
+        results: [...requiredResults, ...optionalResults], 
+        missingRequiredKeys 
+    };
+}
+
+/**
+ * Check for unexpected fields in project specs
+ * @param {Object} projectSpecs - Project specs object
+ * @param {Array} defaultSpecKeys - Keys from default specs
+ * @returns {Array} - Array of unexpected field names
+ */
+function findUnexpectedFields(projectSpecs, defaultSpecKeys) {
+    const projectKeys = Object.keys(projectSpecs.specs?.[0] || {});
+    const allValidFields = getAllValidFields(defaultSpecKeys);
+    
+    return projectKeys.filter(key => !allValidFields.includes(key));
+}
+
 /**
  * Check if a field value has been configured
  * @param {any} projectValue - Value from project specs
@@ -120,61 +213,58 @@ function isFieldConfigured(projectValue, defaultValue) {
 }
 
 /**
- * Evaluate a required field and generate result
+ * Evaluate a field and generate result (unified for required/optional)
  * @param {Object} field - Field definition
  * @param {Object} projectSpecs - Project specs object
  * @param {Object} defaultSpecs - Default specs object
+ * @param {boolean} isRequired - Whether field is required
  * @returns {Object} - Check result
  */
-function evaluateRequiredField(field, projectSpecs, defaultSpecs) {
+function evaluateField(field, projectSpecs, defaultSpecs, isRequired) {
     const hasField = projectSpecs.specs?.[0]?.hasOwnProperty(field.key);
     
     if (!hasField) {
         return {
             name: `${field.description} configuration`,
-            success: false,
-            details: `Required "${field.key}" key is missing in specs.json`
+            success: !isRequired,
+            details: isRequired 
+                ? `Required "${field.key}" key is missing in specs.json`
+                : `Optional "${field.key}" key is not present (this is not required)`
         };
     }
 
     const projectValue = projectSpecs.specs[0][field.key];
     const defaultValue = defaultSpecs.specs?.[0]?.[field.key];
-    let configured = isFieldConfigured(projectValue, defaultValue);
+    const isConfigured = field.allowDefaultValue || isFieldConfigured(projectValue, defaultValue);
     
-    // For fields that can keep their default values, mark as configured
-    if (field.allowDefaultValue) {
-        configured = true;
-    }
-
-    let status;
-    let success = true;
+    // Show warning when fields haven't been configured from their default values
+    const status = isConfigured ? undefined : 'warning';
     
-    if (!configured) {
-        if (field.mustChange) {
-            status = undefined; // No status means it shows as failure
-            success = false;
-        } else {
-            status = 'warning';
-        }
-    }
-
-    let details = '';
-    if (configured) {
-        details = (projectValue === defaultValue && field.allowDefaultValue)
+    const details = isConfigured
+        ? (projectValue === defaultValue && field.allowDefaultValue)
             ? `Default value for ${field.description} is acceptable`
-            : `${field.description} has been changed from default`;
-    } else {
-        details = `${field.description} is still set to default value${['title', 'author'].includes(field.key) ? `: \"${defaultValue}\"` : ''}`;
-    }
+            : `${field.description} has been changed from default`
+        : `${field.description} is still set to default value${mustChangeFields.includes(field.key) ? `: \"${defaultValue}\"` : ''}`;
 
     return {
         name: `${field.description} configuration`,
         status,
-        success,
+        success: true,
         details
     };
 }
 
+/**
+ * Evaluate a required field and generate result
+ * @param {Object} field - Field definition
+ * @param {Object} projectSpecs - Project specs object
+ * @param {Object} defaultSpecs - Default specs object
+ * @returns {Object} - Check result
+ */
+function evaluateRequiredField(field, projectSpecs, defaultSpecs) {
+    return evaluateField(field, projectSpecs, defaultSpecs, true);
+}
+
 /**
  * Evaluate an optional field and generate result
  * @param {Object} field - Field definition
@@ -183,39 +273,7 @@ function evaluateRequiredField(field, projectSpecs, defaultSpecs) {
  * @returns {Object} - Check result
  */
 function evaluateOptionalField(field, projectSpecs, defaultSpecs) {
-    const hasField = projectSpecs.specs?.[0]?.hasOwnProperty(field.key);
-    
-    if (!hasField) {
-        return {
-            name: `${field.description} configuration`,
-            success: true,
-            details: `Optional "${field.key}" key is not present (this is not required)`
-        };
-    }
-
-    const projectValue = projectSpecs.specs[0][field.key];
-    const defaultValue = defaultSpecs.specs?.[0]?.[field.key];
-    let configured = isFieldConfigured(projectValue, defaultValue);
-    
-    if (field.allowDefaultValue) {
-        configured = true;
-    }
-
-    let details = '';
-    if (configured) {
-        details = (projectValue === defaultValue && field.allowDefaultValue)
-            ? `Default value for ${field.description} is acceptable`
-            : `${field.description} has been changed from default`;
-    } else {
-        details = `${field.description} is still set to default value`;
-    }
-
-    return {
-        name: `${field.description} configuration`,
-        status: configured ? undefined : 'warning',
-        success: true, // Always true for optional fields
-        details
-    };
+    return evaluateField(field, projectSpecs, defaultSpecs, false);
 }
 
 /**
@@ -228,22 +286,16 @@ function evaluateOptionalField(field, projectSpecs, defaultSpecs) {
 function generateSummaryResults(results, missingRequiredKeys, unexpectedKeys) {
     const summaryResults = [];
     
-    // Add a summary of missing required fields
-    if (missingRequiredKeys.length > 0) {
-        summaryResults.push({
-            name: 'Required fields check',
-            success: false,
-            details: `Missing required fields: ${missingRequiredKeys.join(', ')}`
-        });
-    } else {
-        summaryResults.push({
-            name: 'Required fields check',
-            success: true,
-            details: 'All required fields are present'
-        });
-    }
+    // Required fields summary
+    summaryResults.push({
+        name: 'Required fields check',
+        success: missingRequiredKeys.length === 0,
+        details: missingRequiredKeys.length > 0 
+            ? `Missing required fields: ${missingRequiredKeys.join(', ')}`
+            : 'All required fields are present'
+    });
 
-    // Check for unexpected fields
+    // Unexpected fields check
     if (unexpectedKeys.length > 0) {
         summaryResults.push({
             name: 'Unexpected fields check',
@@ -253,24 +305,44 @@ function generateSummaryResults(results, missingRequiredKeys, unexpectedKeys) {
     }
 
     // Overall configuration status
-    const fieldResults = results.filter(r =>
-        r.name.includes('configuration') &&
-        !r.name.includes('Overall')
+    const fieldResults = results.filter(r => 
+        r.name.includes('configuration') && !r.name.includes('Overall')
     );
-
+    
     const configuredItemsCount = fieldResults.filter(r => r.success).length;
-    const totalItems = fieldResults.length;
-    const configurationPercentage = Math.round((configuredItemsCount / totalItems) * 100);
+    const configurationPercentage = Math.round((configuredItemsCount / fieldResults.length) * 100);
 
     summaryResults.push({
         name: 'Overall configuration status',
         success: configurationPercentage > 50 && missingRequiredKeys.length === 0,
-        details: `${configurationPercentage}% of specs.json has been configured (${configuredItemsCount}/${totalItems} items)`
+        details: `${configurationPercentage}% of specs.json has been configured (${configuredItemsCount}/${fieldResults.length} items)`
     });
 
     return summaryResults;
 }
 
+/**
+ * Load and parse configuration files
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Object} - Object containing parsed specs and file paths
+ */
+function loadConfigurationFiles(projectRoot) {
+    const projectSpecsPath = path.join(projectRoot, 'specs.json');
+    const defaultSpecsPath = path.join(
+        __dirname, '..', 'install-from-boilerplate', 'boilerplate', 'specs.json'
+    );
+
+    const fileCheckResults = checkFilesExist(projectSpecsPath, defaultSpecsPath);
+    if (fileCheckResults) {
+        return { error: fileCheckResults };
+    }
+
+    const projectSpecs = JSON.parse(fs.readFileSync(projectSpecsPath, 'utf8'));
+    const defaultSpecs = JSON.parse(fs.readFileSync(defaultSpecsPath, 'utf8'));
+    
+    return { projectSpecs, defaultSpecs };
+}
+
 /**
  * Check if specs.json has been configured from default
  * @param {string} projectRoot - Root directory of the project
@@ -278,27 +350,8 @@ function generateSummaryResults(results, missingRequiredKeys, unexpectedKeys) {
  */
 async function checkSpecsJsonConfiguration(projectRoot) {
     try {
-        // Path to the project's specs.json
-        const projectSpecsPath = path.join(projectRoot, 'specs.json');
-
-        // Path to the default boilerplate specs.json
-        const defaultSpecsPath = path.join(
-            __dirname,
-            '..',
-            'install-from-boilerplate',
-            'boilerplate',
-            'specs.json'
-        );
-
-        // Check if required files exist
-        const fileCheckResults = checkFilesExist(projectSpecsPath, defaultSpecsPath);
-        if (fileCheckResults) {
-            return fileCheckResults;
-        }
-
-        // Read both files
-        const projectSpecs = JSON.parse(fs.readFileSync(projectSpecsPath, 'utf8'));
-        const defaultSpecs = JSON.parse(fs.readFileSync(defaultSpecsPath, 'utf8'));
+        const { error, projectSpecs, defaultSpecs } = loadConfigurationFiles(projectRoot);
+        if (error) return error;
 
         const results = [{
             name: 'specs.json exists',
@@ -306,36 +359,17 @@ async function checkSpecsJsonConfiguration(projectRoot) {
             details: 'Project specs.json file found'
         }];
 
-        // Define required and optional fields based on the default specs.json
         const defaultSpecKeys = Object.keys(defaultSpecs.specs?.[0] || {});
-        const { requiredFields, optionalFields } = categorizeFields(defaultSpecKeys);
-
-        // Check each required field
-        const missingRequiredKeys = [];
+        const { results: fieldResults, missingRequiredKeys } = processFieldValidation(
+            projectSpecs, defaultSpecs, defaultSpecKeys
+        );
         
-        for (const field of requiredFields) {
-            const result = evaluateRequiredField(field, projectSpecs, defaultSpecs);
-            if (!result.success && result.details.includes('missing')) {
-                missingRequiredKeys.push(field.key);
-            }
-            results.push(result);
-        }
-
-        // Check optional fields
-        for (const field of optionalFields) {
-            results.push(evaluateOptionalField(field, projectSpecs, defaultSpecs));
-        }
-
-        // Check for unexpected fields
-        const allStandardKeys = [...requiredFields, ...optionalFields].map(f => f.key);
-        const unexpectedKeys = Object.keys(projectSpecs.specs?.[0] || {})
-            .filter(key => !allStandardKeys.includes(key));
-
-        // Add summary results
+        results.push(...fieldResults);
+        
+        const unexpectedKeys = findUnexpectedFields(projectSpecs, defaultSpecKeys);
         const summaryResults = generateSummaryResults(results, missingRequiredKeys, unexpectedKeys);
-        results.push(...summaryResults);
-
-        return results;
+        
+        return [...results, ...summaryResults];
 
     } catch (error) {
         console.error('Error checking specs.json configuration:', error);

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/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
-};