spec-up-t 1.4.1 → 1.6.0-beta.1

package/src/run-healthcheck.js

@@ -0,0 +1,177 @@
+/**
+ * Health Check Integration Script for spec-up-t
+ * 
+ * This script integrates the spec-up-t-healthcheck tool to validate consuming projects.
+ * It runs FROM spec-up-t (menu option 7) but checks the CONSUMING project (current directory).
+ * 
+ * Usage (from consuming project):
+ *   npm run healthCheck
+ * 
+ * Or via spec-up-t menu:
+ *   npm run menu -> [7] Run health check
+ * 
+ * Options:
+ *   --format text|json|html    Output format (default: html)
+ *   --output <file>            Output file path
+ *   --checks <checks>          Comma-separated list of specific checks
+ * 
+ * Examples:
+ *   node run-healthcheck.js
+ *   node run-healthcheck.js --format json
+ *   node run-healthcheck.js --format html --output health-report.html
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Parse command line arguments
+ * Handles both direct node invocations and npm script invocations
+ * 
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    format: 'html',  // Changed default to HTML for better user experience
+    output: null,
+    checks: null
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--format' && args[i + 1]) {
+      options.format = args[i + 1];
+      i++;
+    } else if (args[i] === '--output' && args[i + 1]) {
+      options.output = args[i + 1];
+      i++;
+    } else if (args[i] === '--checks' && args[i + 1]) {
+      options.checks = args[i + 1].split(',');
+      i++;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Main execution function
+ * 
+ * Runs health checks on the CONSUMING PROJECT (current working directory).
+ * This script is part of spec-up-t but validates the project that uses spec-up-t.
+ */
+async function main() {
+  try {
+    console.log('🏥 Spec-Up-T Health Check\n');
+    console.log('📍 Checking consuming project in:', process.cwd());
+    console.log('');
+
+    // Parse command line arguments
+    const options = parseArgs();
+
+    // Import the health check tool
+    const {
+      createProvider,
+      runHealthChecks,
+      formatResultsAsText,
+      formatResultsAsJson,
+      formatResultsAsHtml
+    } = await import('spec-up-t-healthcheck');
+
+    // Create a provider for the CURRENT WORKING DIRECTORY (the consuming project)
+    const provider = createProvider(process.cwd());
+
+    // Run health checks on the consuming project
+    console.log('🔍 Running health checks on consuming project...');
+    const healthCheckOptions = {};
+    if (options.checks) {
+      healthCheckOptions.checks = options.checks;
+    }
+
+    const results = await runHealthChecks(provider, healthCheckOptions);
+
+    // Display summary
+    console.log('\n📊 Health Check Summary:');
+    console.log(`   Total Checks: ${results.summary.total}`);
+    console.log(`   ✅ Passed: ${results.summary.passed}`);
+    console.log(`   ❌ Failed: ${results.summary.failed}`);
+    console.log(`   ⚠️  Warnings: ${results.summary.warnings}`);
+    console.log(`   ⏭️  Skipped: ${results.summary.skipped}`);
+    console.log(`   📈 Health Score: ${results.summary.score}%\n`);
+
+    // Format results based on requested format
+    let output;
+    let defaultFilename;
+
+    switch (options.format) {
+      case 'json':
+        output = formatResultsAsJson(results);
+        defaultFilename = 'health-report.json';
+        break;
+
+      case 'html':
+        output = formatResultsAsHtml(results, {
+          title: 'Spec-Up-T Project Health Check',
+          repositoryUrl: results.provider.repoPath ? 
+            `file://${results.provider.repoPath}` : undefined
+        });
+        defaultFilename = 'health-report.html';
+        break;
+
+      case 'text':
+      default:
+        output = formatResultsAsText(results);
+        defaultFilename = 'health-report.txt';
+        break;
+    }
+
+    // Determine output path
+    const outputPath = options.output || defaultFilename;
+
+    // Save to file
+    await fs.writeFile(outputPath, output);
+    console.log(`📄 Report saved to: ${outputPath}`);
+
+    // For HTML format, try to open in browser
+    if (options.format === 'html' && !options.output) {
+      try {
+        const { openHtmlFile } = require('./utils/file-opener');
+        await openHtmlFile(path.resolve(outputPath));
+        console.log('🌐 Opening report in browser...');
+      } catch (error) {
+        console.log('ℹ️  Tip: Open the report manually in your browser');
+      }
+    }
+
+    // For text format, also print to console
+    if (options.format === 'text') {
+      console.log('\n' + output);
+    }
+
+    // Exit with appropriate code
+    if (results.summary.hasErrors) {
+      console.error('\n❌ Health check completed with errors');
+      console.error('   Please review the report for details');
+      process.exit(1);
+    } else if (results.summary.hasWarnings) {
+      console.warn('\n⚠️  Health check completed with warnings');
+      process.exit(0);
+    } else {
+      console.log('\n✅ Health check completed successfully');
+      console.log('   All checks passed!');
+      process.exit(0);
+    }
+
+  } catch (error) {
+    console.error('\n❌ Health check failed:', error.message);
+    console.error('\nDetails:', error.stack);
+    console.error('\nTroubleshooting:');
+    console.error('  - Ensure you are running this from a consuming project directory');
+    console.error('  - Check that spec-up-t-healthcheck is properly installed');
+    console.error('  - Verify the consuming project has a valid package.json');
+    process.exit(1);
+  }
+}
+
+// Run the script
+main();

package/src/utils/logger.js

@@ -1,8 +1,12 @@
 const chalk = require('chalk');
+const messageCollector = require('./message-collector');
 
 /**
  * Logger utility with color-coded console output
  * Provides consistent logging across the spec-up-t application
+ * 
+ * All messages are automatically collected when message collection is active,
+ * allowing healthchecks and other tools to consume the output in JSON format.
  */
 class Logger {
     /**
@@ -10,27 +14,128 @@ class Logger {
      */
     static success(message, ...args) {
         console.log(chalk.green('✅'), chalk.green(message), ...args);
+        messageCollector.addMessage('success', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Error messages - red with X mark
+     * 
+     * Enhanced error logging with optional context and actionable guidance.
+     * 
+     * @param {string} message - The main error message
+     * @param {...any} args - Additional arguments. Can include:
+     *   - Regular values (strings, numbers, objects) for message formatting
+     *   - An options object (if last arg is object with 'hint', 'context', or 'details' keys):
+     *     - hint: Actionable suggestion for fixing the error
+     *     - context: Additional context about where/why the error occurred
+     *     - details: Technical details or error objects
+     * 
+     * @example
+     * Logger.error('File not found', { 
+     *   context: 'specs.json',
+     *   hint: 'Create a specs.json file in your project root',
+     *   details: error.message 
+     * });
      */
     static error(message, ...args) {
-        console.log(chalk.red('❌'), chalk.red(message), ...args);
+        // Extract options object if present (last arg with special keys)
+        const lastArg = args[args.length - 1];
+        const isOptionsObject = lastArg && typeof lastArg === 'object' &&
+            (lastArg.hint || lastArg.context || lastArg.details);
+
+        const options = isOptionsObject ? args.pop() : {};
+        const regularArgs = args;
+
+        // Display main error message
+        console.log(chalk.red('❌'), chalk.red(message), ...regularArgs);
+
+        // Display context if provided - helps identify the scope of the error
+        if (options.context) {
+            console.log(chalk.red('   Context:'), chalk.gray(options.context));
+        }
+
+        // Display technical details if provided - useful for debugging
+        if (options.details) {
+            const detailsStr = typeof options.details === 'object'
+                ? JSON.stringify(options.details, null, 2)
+                : String(options.details);
+            console.log(chalk.red('   Details:'), chalk.gray(detailsStr));
+        }
+
+        // Display actionable hint if provided - most valuable for authors
+        if (options.hint) {
+            console.log(chalk.yellow('   💡 How to fix:'), chalk.yellow(options.hint));
+        }
+
+        // Collect message with all context for healthcheck/JSON output
+        messageCollector.addMessage('error', message, [...regularArgs, options]);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Warning messages - yellow with warning symbol
+     * 
+     * Enhanced warning logging with optional context and actionable guidance.
+     * 
+     * @param {string} message - The main warning message
+     * @param {...any} args - Additional arguments. Can include:
+     *   - Regular values (strings, numbers, objects) for message formatting
+     *   - An options object (if last arg is object with 'hint', 'context', or 'details' keys):
+     *     - hint: Actionable suggestion for addressing the warning
+     *     - context: Additional context about where/why the warning occurred
+     *     - details: Technical details or related information
+     * 
+     * @example
+     * Logger.warn('Using fallback configuration', { 
+     *   context: 'specs.json missing optional field',
+     *   hint: 'Add "output_path" to specs.json for better control',
+     *   details: 'Using default: ./docs' 
+     * });
      */
     static warn(message, ...args) {
-        console.log(chalk.yellow('🟡'), chalk.yellow(message), ...args);
+        // Extract options object if present (last arg with special keys)
+        const lastArg = args[args.length - 1];
+        const isOptionsObject = lastArg && typeof lastArg === 'object' &&
+            (lastArg.hint || lastArg.context || lastArg.details);
+
+        const options = isOptionsObject ? args.pop() : {};
+        const regularArgs = args;
+
+        // Display main warning message
+        console.log(chalk.keyword('orange')('❗'), chalk.yellow(message), ...regularArgs);
+
+        // Display context if provided - helps identify the scope of the warning
+        if (options.context) {
+            console.log(chalk.yellow('   Context:'), chalk.gray(options.context));
+        }
+
+        // Display technical details if provided - useful for understanding the situation
+        if (options.details) {
+            const detailsStr = typeof options.details === 'object'
+                ? JSON.stringify(options.details, null, 2)
+                : String(options.details);
+            console.log(chalk.yellow('   Details:'), chalk.gray(detailsStr));
+        }
+
+        // Display actionable hint if provided - helps authors improve their spec
+        if (options.hint) {
+            console.log(chalk.cyan('   💡 Suggestion:'), chalk.cyan(options.hint));
+        }
+
+        // Collect message with all context for healthcheck/JSON output
+        messageCollector.addMessage('warn', message, [...regularArgs, options]);
+
+        console.log(); // Extra newline for readability
     }
 
-    /**
-     * Info messages - blue with info symbol
-     */
     static info(message, ...args) {
-        console.log(chalk.blue('📒'), chalk.blue(message), ...args);
+        console.log(chalk.blue('📋'), chalk.blue(message), ...args);
+        messageCollector.addMessage('info', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -38,6 +143,9 @@ class Logger {
      */
     static process(message, ...args) {
         console.log(chalk.cyan('🔄'), chalk.cyan(message), ...args);
+        messageCollector.addMessage('process', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -45,13 +153,19 @@ class Logger {
      */
     static debug(message, ...args) {
         console.log(chalk.gray('🔍'), chalk.gray(message), ...args);
+        messageCollector.addMessage('debug', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Highlight important data - magenta
      */
     static highlight(message, ...args) {
-        console.log(chalk.blue('✨'), chalk.blue(message), ...args);
+        console.log(chalk.blue('📋'), chalk.blue(message), ...args);
+        messageCollector.addMessage('highlight', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -59,6 +173,9 @@ class Logger {
      */
     static separator() {
         console.log(chalk.gray('═'.repeat(60)));
+        messageCollector.addMessage('separator', '═'.repeat(60), []);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -67,7 +184,11 @@ class Logger {
     static progress(current, total, message) {
         const percentage = Math.round((current / total) * 100);
         const bar = '█'.repeat(Math.floor(percentage / 5)) + '░'.repeat(20 - Math.floor(percentage / 5));
-        console.log(chalk.cyan(`📊 [${bar}] ${percentage}% ${message}`));
+        const progressMessage = `[${bar}] ${percentage}% ${message}`;
+        console.log(chalk.cyan(`📊 ${progressMessage}`));
+        messageCollector.addMessage('progress', progressMessage, [current, total]);
+
+        console.log(); // Extra newline for readability
     }
 }
 

package/src/utils/message-collector.js

@@ -0,0 +1,144 @@
+/**
+ * @file Message collector for capturing console output from menu operations
+ * 
+ * This module wraps the Logger to intercept and store all console messages
+ * produced during menu [1] (render) and menu [4] (collect external references)
+ * operations, storing them in JSON format for consumption by healthchecks.
+ * 
+ * The captured messages are stored in `.cache/console-messages.json` with
+ * structured metadata including:
+ * - timestamp: ISO timestamp of when the message was logged
+ * - type: success, error, warn, info, process, highlight, debug, separator
+ * - message: the actual message text
+ * - operation: which menu operation triggered this (render or collectExternalReferences)
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Message collection state
+ */
+const messageStore = {
+    messages: [],
+    currentOperation: null,
+    isCollecting: false
+};
+
+/**
+ * Start collecting messages for a specific operation
+ * @param {string} operation - Operation name ('render' or 'collectExternalReferences')
+ */
+function startCollecting(operation) {
+    messageStore.isCollecting = true;
+    messageStore.currentOperation = operation;
+}
+
+/**
+ * Stop collecting messages
+ */
+function stopCollecting() {
+    messageStore.isCollecting = false;
+    messageStore.currentOperation = null;
+}
+
+/**
+ * Add a message to the collection
+ * @param {string} type - Message type (success, error, warn, etc.)
+ * @param {string} message - Message text
+ * @param {Array} args - Additional arguments passed to logger
+ */
+function addMessage(type, message, args = []) {
+    if (!messageStore.isCollecting) {
+        return;
+    }
+
+    const messageEntry = {
+        timestamp: new Date().toISOString(),
+        type,
+        message: String(message),
+        operation: messageStore.currentOperation,
+        additionalData: args.length > 0 ? args.map(arg => String(arg)) : undefined
+    };
+
+    messageStore.messages.push(messageEntry);
+}
+
+/**
+ * Save collected messages to JSON file
+ * Each run creates a fresh file, replacing any existing messages.
+ * 
+ * @param {string} [outputPath] - Optional custom output path
+ * @returns {Promise<string>} Path to the saved file
+ */
+async function saveMessages(outputPath) {
+    const cacheDir = path.join(process.cwd(), '.cache');
+    const defaultPath = path.join(cacheDir, 'console-messages.json');
+    const filePath = outputPath || defaultPath;
+
+    await fs.ensureDir(path.dirname(filePath));
+
+    const output = {
+        metadata: {
+            generatedAt: new Date().toISOString(),
+            totalMessages: messageStore.messages.length,
+            operations: [...new Set(messageStore.messages.map(m => m.operation))],
+            messagesByType: messageStore.messages.reduce((acc, msg) => {
+                acc[msg.type] = (acc[msg.type] || 0) + 1;
+                return acc;
+            }, {})
+        },
+        messages: messageStore.messages
+    };
+
+    await fs.writeJson(filePath, output, { spaces: 2 });
+
+    return filePath;
+}
+
+/**
+ * Clear all collected messages
+ */
+function clearMessages() {
+    messageStore.messages = [];
+}
+
+/**
+ * Get current messages (without saving)
+ * @returns {Array} Array of message objects
+ */
+function getMessages() {
+    return [...messageStore.messages];
+}
+
+/**
+ * Get statistics about collected messages
+ * @returns {Object} Statistics object
+ */
+function getStatistics() {
+    return {
+        total: messageStore.messages.length,
+        byType: messageStore.messages.reduce((acc, msg) => {
+            acc[msg.type] = (acc[msg.type] || 0) + 1;
+            return acc;
+        }, {}),
+        byOperation: messageStore.messages.reduce((acc, msg) => {
+            if (msg.operation) {
+                acc[msg.operation] = (acc[msg.operation] || 0) + 1;
+            }
+            return acc;
+        }, {}),
+        isCollecting: messageStore.isCollecting,
+        currentOperation: messageStore.currentOperation
+    };
+}
+
+module.exports = {
+    startCollecting,
+    stopCollecting,
+    addMessage,
+    saveMessages,
+    clearMessages,
+    getMessages,
+    getStatistics
+};

package/src/utils/regex-patterns.js

@@ -109,12 +109,14 @@ const templateTags = {
    * Pattern breakdown:
    * - ^def$ → Exact match for "def" (definition)
    * - ^ref$ → Exact match for "ref" (reference)
+   * - ^iref$ → Exact match for "iref" (inline reference - copies existing term)
    * - ^xref → Starts with "xref" (external reference)
    * - ^tref → Starts with "tref" (typed reference)
    * 
    * Examples:
    * - "def" → matches
    * - "ref" → matches
+   * - "iref" → matches
    * - "xref" → matches
    * - "tref" → matches
    * - "xref:spec,term" → matches (starts with xref)
@@ -122,7 +124,7 @@ const templateTags = {
    * Flags:
    * - i: case-insensitive matching
    */
-  terminology: /^def$|^ref$|^xref|^tref$/i
+  terminology: /^def$|^ref$|^iref$|^xref|^tref$/i
 };
 
 /**

package/templates/template.html

@@ -8,7 +8,7 @@
     <meta name="author" content="${author}">
     <meta property="spec-up-t:github-repo-info" content="${githubRepoInfo}">
     <link rel="icon" href="${specFavicon}" type="image/x-icon">
-    <meta name="generator" content="Spec-Up-T" />
+    <meta name="generator" content="Spec-Up-T">
     <title>${title}</title>
 
     ${assetsHead}
@@ -19,7 +19,7 @@
     <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.5/font/bootstrap-icons.min.css" rel="stylesheet">
 </head>
 
-<body features="${features}">
+<body>
     <!-- Skip to content link for accessibility -->
     <a href="#content" class="screen-reader-text">Skip to content</a>
 
@@ -128,7 +128,7 @@
         </button>
 
         <a id="logo" href="${specLogoLink}">
-            <img class="d-print-none m-1" src="${specLogo}" alt="" />
+            <img class="d-print-none m-1" src="${specLogo}" alt="">
         </a>
 
         <!-- Spacer to push the following elements to the right -->
@@ -138,7 +138,7 @@
         <div class="d-flex align-items-center service-menu d-print-none">
 
             <!-- Settings side menu -->
-            <button id="repo_settings" animate class="btn btn-sm btn-outline-secondary ms-2" type="button"
+            <button id="repo_settings" class="btn btn-sm btn-outline-secondary ms-2" type="button"
                 data-bs-toggle="offcanvas" data-bs-target="#offcanvasSettings" aria-controls="offcanvasSettings">
                 <svg class="bi" width="1em" height="1em" aria-hidden="true">
                     <use href="#gear-wide-connected"></use>
@@ -249,7 +249,7 @@
 
     <div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasSettings" aria-labelledby="offcanvasSettingsLabel">
         <div class="offcanvas-header">
-            <h5 class="offcanvas-title mt-0" id="offcanvasSettings">Settings</h5>
+            <h5 class="offcanvas-title mt-0" id="offcanvasSettingsLabel">Settings</h5>
             <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
         </div>
         <div class="offcanvas-body p-0">
@@ -259,7 +259,7 @@
                 aria-label="Enter GitHub Token">
                 Enter GitHub Token
             </button>
-            <button id="repo_issues" issue-count animate class="btn btn-menu-item m-0 mb-1 border-start-0 border-end-0"
+            <button id="repo_issues" data-issue-count data-animate class="btn btn-menu-item m-0 mb-1 border-start-0 border-end-0"
                 type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasIssues"
                 aria-controls="offcanvasIssues">
                 Issues