spec-up-t 1.3.1 → 1.4.0

package/src/pipeline/rendering/render-utils.js

@@ -0,0 +1,154 @@
+/**
+ * Utility functions for rendering and processing specs.
+ * This module centralizes helper functions to reduce complexity in index.js.
+ * These functions handle tasks like path normalization, term lookups, and markdown processing.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { templateTags, paths, whitespace } = require('../../utils/regex-patterns.js');
+
+// Constants used in rendering and processing
+const katexRules = ['math_block', 'math_inline'];
+const replacerRegex = templateTags.replacer;
+const replacerArgsRegex = templateTags.argsSeparator;
+const replacers = [
+  {
+    test: 'insert',
+    transform: function (originalMatch, type, path) {
+      if (!path) return '';
+      return fs.readFileSync(path, 'utf8');
+    }
+  }
+];
+
+/**
+ * Creates a script element containing XTref data for embedding in HTML.
+ * Tests if xtrefs-data.js exists; if not, returns an empty string.
+ * @returns {string} The script element or empty string.
+ */
+function createScriptElementWithXTrefDataForEmbeddingInHtml() {
+  const inputPath = path.join('.cache', 'xtrefs-data.js');
+  let xtrefsData = '';
+  if (fs.existsSync(inputPath)) {
+    xtrefsData = '<script>' + fs.readFileSync(inputPath, 'utf8') + '</script>';
+  }
+  return xtrefsData;
+}
+
+/**
+ * Looks up an xref term from the allXTrefs data.
+ * @param {string} externalSpec - The external spec identifier.
+ * @param {string} termName - The term name to look up.
+ * @returns {Object|null} The term object if found, null otherwise.
+ */
+function lookupXrefTerm(externalSpec, termName) {
+  try {
+    const xtrefsPath = path.join('.cache', 'xtrefs-data.json');
+    if (!fs.existsSync(xtrefsPath)) {
+      return null;
+    }
+
+    const allXTrefs = fs.readJsonSync(xtrefsPath);
+    if (!allXTrefs || !allXTrefs.xtrefs) {
+      return null;
+    }
+
+    const termKey = termName.replace(whitespace.oneOrMore, '-').toLowerCase();
+    const foundTerm = allXTrefs.xtrefs.find(xtref =>
+      xtref.externalSpec === externalSpec &&
+      xtref.term === termKey &&
+      xtref.source === 'xref'
+    );
+
+    return foundTerm || null;
+  } catch (error) {
+    console.warn(`Error looking up xref term ${externalSpec}:${termName}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * Processes custom tag patterns in markdown content and applies transformation functions.
+ * Scans for patterns like [[tref:spec,term]] and replaces them with HTML equivalents.
+ * @param {string} doc - The markdown document to process.
+ * @returns {string} The processed document with tags replaced.
+ */
+function applyReplacers(doc) {
+  const { processWithEscapes } = require('../preprocessing/escape-processor.js');
+  return processWithEscapes(doc, function (content) {
+    return content.replace(replacerRegex, function (match, type, args) {
+      let replacer = replacers.find(r => type.trim().match(r.test));
+      if (replacer) {
+        let argsArray = args ? args.trim().split(replacerArgsRegex) : [];
+        return replacer.transform(match, type, ...argsArray);
+      }
+      return match;
+    });
+  });
+}
+
+/**
+ * Normalizes a path by trimming trailing slashes and adding a leading slash.
+ * @param {string} path - The path to normalize.
+ * @returns {string} The normalized path.
+ */
+function normalizePath(path) {
+  return path.trim().replace(paths.trailingSlash, '') + '/';
+}
+
+/**
+ * Renders a reference group for a given type.
+ * @param {string} type - The type of reference group.
+ * @param {Object} specGroups - The spec groups object.
+ * @returns {string} The rendered HTML for the reference group.
+ */
+function renderRefGroup(type, specGroups) {
+  let group = specGroups[type];
+  if (!group) return '';
+
+  let html = Object.keys(group).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())).reduce((html, name) => {
+    let ref = group[name];
+    return html += `
+    <dt id="ref:${name}">${name}</dt>
+    <dd>
+      <cite><a href="${ref.href}">${ref.title}</a></cite>.
+      ${ref.authors.join('; ')}; ${ref.rawDate}. <span class="reference-status">Status: ${ref.status}</span>.
+    </dd>
+  `;
+  }, '<dl class="reference-list">');
+  return `\n${html}\n</dl>\n`;
+}
+
+/**
+ * Finds the KaTeX distribution path.
+ * Checks common locations for the KaTeX package.
+ * @returns {string} The path to the KaTeX distribution.
+ * @throws {Error} If KaTeX distribution cannot be located.
+ */
+function findKatexDist() {
+  const relpath = "node_modules/katex/dist";
+  const paths = [
+    path.join(process.cwd(), relpath),
+    path.join(__dirname, relpath),
+  ];
+  for (const abspath of paths) {
+    if (fs.existsSync(abspath)) {
+      return abspath;
+    }
+  }
+  throw new Error("katex distribution could not be located");
+}
+
+module.exports = {
+  katexRules,
+  replacerRegex,
+  replacerArgsRegex,
+  replacers,
+  createScriptElementWithXTrefDataForEmbeddingInHtml,
+  lookupXrefTerm,
+  applyReplacers,
+  normalizePath,
+  renderRefGroup,
+  findKatexDist
+};

package/src/utils/LOGGER.md

@@ -0,0 +1,81 @@
+# Logger Utility
+
+A centralized logging utility for the spec-up-t project that provides consistent, color-coded console output using chalk.
+
+## Features
+
+- **Color-coded messages** for different log levels
+- **Consistent icons** and formatting
+- **Progress indicators** with visual progress bars
+- **Section separators** for organized output
+- **Terminal-friendly** symbols that work across platforms
+
+## Usage
+
+```javascript
+const Logger = require('./src/utils/logger');
+
+// Success messages (green with checkmark)
+Logger.success('Operation completed successfully');
+
+// Error messages (red with X mark)
+Logger.error('Failed to process request');
+
+// Warning messages (yellow with warning symbol)
+Logger.warn('Configuration file not found, using defaults');
+
+// Info messages (blue with info symbol)
+Logger.info('Processing 42 external references');
+
+// Processing status (cyan with arrow)
+Logger.process('Processing repository: owner/repo (15 terms)');
+
+// Highlighted information (magenta with star)
+Logger.highlight('Grouped 42 terms into 6 repositories');
+
+// Progress indicators
+Logger.progress(3, 5, 'Processing terms'); // Shows: [████████████░░░░░░░░] 60% Processing terms
+
+// Section separators
+Logger.separator(); // Shows: ════════════════════════════════════════════════════════════
+```
+
+## Log Levels
+
+| Method | Color | Icon | Purpose |
+|--------|-------|------|---------|
+| `success()` | Green | ✓ | Successful operations |
+| `error()` | Red | ✗ | Errors and failures |
+| `warn()` | Yellow | ⚠ | Warnings and non-critical issues |
+| `info()` | Blue | ℹ | General information |
+| `process()` | Cyan | → | Processing status updates |
+| `highlight()` | Magenta | ★ | Important data/summaries |
+| `debug()` | Gray | ◦ | Debug information |
+
+## Migration from console.log
+
+**Before:**
+```javascript
+console.log(`✅ Successfully processed ${count} items`);
+console.log(`❌ Failed to fetch data from ${url}`);
+console.log(`⚠️ Missing configuration file`);
+```
+
+**After:**
+```javascript
+Logger.success(`Successfully processed ${count} items`);
+Logger.error(`Failed to fetch data from ${url}`);
+Logger.warn('Missing configuration file');
+```
+
+## Dependencies
+
+- `chalk@4` - For terminal colors (CommonJS compatible version)
+
+## Installation
+
+The logger is automatically available when chalk v4 is installed:
+
+```bash
+npm install chalk@4
+```

package/src/utils/{doesUrlExist.js → does-url-exist.js}

@@ -1,4 +1,5 @@
 const axios = require('axios');
+const Logger = require('./logger');
 
 /**
  * Checks if a URL returns a 200 status code.
@@ -12,11 +13,11 @@ async function doesUrlExist(url) {
     } catch (error) {
         // Handle specific error cases for better logging/debugging
         if (error.response && error.response.status === 404) {
-            console.debug('URL does not exist:', url);
+            Logger.debug('URL does not exist:', url);
         } else if (error.code === 'ENOTFOUND' || error.code === 'ECONNABORTED') {
-            console.debug('Network issues with URL:', url);
+            Logger.debug('Network issues with URL:', url);
         } else {
-            console.debug('Failed to check URL:', url, error.message);
+            Logger.debug('Failed to check URL:', url, error.message);
         }
         return false;
     }

package/src/utils/fetch.js

@@ -3,6 +3,7 @@
  */
 const fs = require('fs');
 const path = require('path');
+const Logger = require('./logger');
 
 /**
  * Fetches the .cache/specs-generated.json file and returns it as a JavaScript object
@@ -21,7 +22,7 @@ function fetchSpecs() {
     
     return specs;
   } catch (error) {
-    console.error('Error fetching .cache/specs-generated.json:', error.message);
+    Logger.error('Error fetching .cache/specs-generated.json:', error.message);
     return null;
   }
 }
@@ -43,7 +44,7 @@ function fetchExternalTerms() {
     
     return xtrefs;
   } catch (error) {
-    console.error('Error fetching .cache/xtrefs-data.json:', error.message);
+    Logger.error('Error fetching .cache/xtrefs-data.json:', error.message);
     return null;
   }
 }
@@ -65,7 +66,7 @@ async function fetchSpecsAsync() {
     
     return specs;
   } catch (error) {
-    console.error('Error fetching .cache/specs-generated.json:', error.message);
+    Logger.error('Error fetching .cache/specs-generated.json:', error.message);
     return null;
   }
 }
@@ -87,7 +88,7 @@ async function fetchExternalTermsAsync() {
     
     return xtrefs;
   } catch (error) {
-    console.error('Error fetching .cache/xtrefs-data.json:', error.message);
+    Logger.error('Error fetching .cache/xtrefs-data.json:', error.message);
     return null;
   }
 }

package/src/utils/file-opener.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const { spawnSync } = require('child_process');
+const Logger = require('./logger');
 
 /**
  * Helper function to get the absolute path of a command
@@ -35,7 +36,7 @@ function getCommandPath(command) {
     
     // If we can't find the absolute path, return the command name as fallback
     // This maintains functionality while logging the issue
-    console.warn(`Warning: Could not find absolute path for command '${command}', using relative path as fallback`);
+    Logger.warn(`Could not find absolute path for command '${command}', using relative path as fallback`);
     return command;
 }
 
@@ -67,7 +68,7 @@ function openFile(filePath) {
         const result = spawnSync(openCommand, [filePath], { stdio: 'ignore' });
         return result.status === 0;
     } catch (error) {
-        console.error('Failed to open file:', error);
+        Logger.error('Failed to open file:', error);
         return false;
     }
 }

package/src/utils/git-info.js

@@ -0,0 +1,77 @@
+/**
+ * Git information utility
+ * 
+ * Provides functions to extract Git repository information including
+ * the current branch name and repository details from the working directory.
+ * 
+ * @author Spec-Up-T Team
+ * @since 2025-08-31
+ */
+
+const { execSync } = require('child_process');
+const Logger = require('./logger');
+
+/**
+ * Gets the current Git branch name
+ * 
+ * @returns {string} The current branch name, or 'main' as fallback
+ */
+function getCurrentBranch() {
+    try {
+        const branch = execSync('git branch --show-current', { 
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        
+        if (branch) {
+            Logger.info(`Current git branch: ${branch}`);
+            return branch;
+        }
+        
+        // Fallback to checking HEAD if branch name is empty (detached HEAD)
+        const head = execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        
+        if (head && head !== 'HEAD') {
+            Logger.info(`Current git branch (from HEAD): ${head}`);
+            return head;
+        }
+        
+        Logger.warn('Could not determine git branch, using fallback: main');
+        return 'main';
+    } catch (error) {
+        Logger.warn(`Could not get git branch (${error.message}), using fallback: main`);
+        return 'main';
+    }
+}
+
+/**
+ * Creates GitHub repository information meta tag content
+ * 
+ * @param {Object} spec - The spec configuration object
+ * @returns {string} Meta tag content in format "username,repo,branch"
+ */
+function getGithubRepoInfo(spec) {
+    try {
+        const source = spec.source || {};
+        const account = source.account || 'unknown';
+        const repo = source.repo || 'unknown';
+        const branch = getCurrentBranch();
+        
+        const content = `${account},${repo},${branch}`;
+        Logger.info(`GitHub repo info: ${content}`);
+        return content;
+    } catch (error) {
+        Logger.warn(`Error generating GitHub repo info: ${error.message}`);
+        return 'unknown,unknown,main';
+    }
+}
+
+module.exports = {
+    getCurrentBranch,
+    getGithubRepoInfo
+};

package/src/utils/logger.js

@@ -0,0 +1,74 @@
+const chalk = require('chalk');
+
+/**
+ * Logger utility with color-coded console output
+ * Provides consistent logging across the spec-up-t application
+ */
+class Logger {
+    /**
+     * Success messages - green with checkmark
+     */
+    static success(message, ...args) {
+        console.log(chalk.green('✅'), chalk.green(message), ...args);
+    }
+
+    /**
+     * Error messages - red with X mark
+     */
+    static error(message, ...args) {
+        console.log(chalk.red('❌'), chalk.red(message), ...args);
+    }
+
+    /**
+     * Warning messages - yellow with warning symbol
+     */
+    static warn(message, ...args) {
+        console.log(chalk.yellow('🟡'), chalk.yellow(message), ...args);
+    }
+
+    /**
+     * Info messages - blue with info symbol
+     */
+    static info(message, ...args) {
+        console.log(chalk.blue('📒'), chalk.blue(message), ...args);
+    }
+
+    /**
+     * Processing messages - cyan
+     */
+    static process(message, ...args) {
+        console.log(chalk.cyan('🔄'), chalk.cyan(message), ...args);
+    }
+
+    /**
+     * Debug messages - gray
+     */
+    static debug(message, ...args) {
+        console.log(chalk.gray('🔍'), chalk.gray(message), ...args);
+    }
+
+    /**
+     * Highlight important data - magenta
+     */
+    static highlight(message, ...args) {
+        console.log(chalk.magenta('✨'), chalk.magenta(message), ...args);
+    }
+
+    /**
+     * Section separators
+     */
+    static separator() {
+        console.log(chalk.gray('═'.repeat(60)));
+    }
+
+    /**
+     * Progress indicator with counts
+     */
+    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}`));
+    }
+}
+
+module.exports = Logger;