spec-up-t 1.2.6 → 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/assets/js/collapse-definitions.js

@@ -57,7 +57,8 @@ function collapseDefinitions() {
             "See more about",
             "See more on",
             "See more at",
-            "More:"
+            "More:",
+            "Supporting definitions:"
         ];
         return definitionHidePrefixes.some(prefix => content.startsWith(prefix));
     }

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/jest.config.js

@@ -0,0 +1,20 @@
+module.exports = {
+  collectCoverageFrom: [
+    'src/**/*.{js,jsx}',
+    '!src/**/*.test.{js,jsx}',
+    '!src/**/__tests__/**',
+    '!src/**/__mocks__/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+  testEnvironment: 'node',
+  verbose: true,
+}; 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.2.6",
+  "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": {
@@ -70,6 +70,7 @@
     "jest": "^29.7.0"
   },
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
+    "test": "jest",
+    "test:coverage": "jest --coverage"
   }
 }

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/{output-gitignore-checker.js → destination-gitignore-checker.js}

@@ -1,6 +1,17 @@
+/**
+ * @file destination-gitignore-checker.js
+ * @description Checks if the final destination directory (from output_path in specs.json) 
+ * is being ignored by Git. This is the directory where index.html is generated, 
+ * NOT the temporary .cache directory (formerly called "output").
+ * 
+ * Important: This file deals with concept #1 (output_path from specs.json),
+ * not concept #2 (the temporary .cache directory for build artifacts).
+ */
+
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { spawnSync } = require('child_process');
+const fileOpener = require('../utils/file-opener');
 
 /**
  * Checks if a path is gitignored
@@ -13,8 +24,11 @@ function isPathGitIgnored(projectRoot, targetPath) {
     // Use git check-ignore to determine if the path is ignored
     // If command exits with status 0, path is ignored
     // If command exits with status 1, path is not ignored
-    execSync(`git -C "${projectRoot}" check-ignore -q "${targetPath}"`, { stdio: 'ignore' });
-    return true; // Path is ignored (command exited with status 0)
+    const gitPath = fileOpener.getCommandPath('git');
+    const result = spawnSync(gitPath, ['-C', projectRoot, 'check-ignore', '-q', targetPath], { 
+      stdio: 'ignore' 
+    });
+    return result.status === 0; // Path is ignored (command exited with status 0)
   } catch (error) {
     console.log(`Error checking if path is gitignored: ${error.message}`);
     return false; // Path is not ignored (command exited with non-zero status)
@@ -87,11 +101,11 @@ function extractOutputPath(specsPath) {
 }
 
 /**
- * Check if the output directory exists
+ * Check if the final destination directory (from output_path) exists
  * @param {string} projectRoot - Root directory of the project
  * @param {string} outputPath - Output path from specs.json
  * @param {string} normalizedPath - Normalized output path
- * @returns {Object} - Result with output directory check
+ * @returns {Object} - Result with final destination directory check
  */
 function checkOutputDirExists(projectRoot, outputPath, normalizedPath) {
   // Check if the path exists
@@ -100,17 +114,17 @@ function checkOutputDirExists(projectRoot, outputPath, normalizedPath) {
   
   if (!outputPathExists) {
     return {
-      name: 'Output directory existence',
+      name: 'Final destination directory existence',
       status: 'warning',
       success: true, // Still considered a "success" for backward compatibility
-      details: `Output directory "${outputPath}" does not exist yet. This is OK if you haven't rendered the specs yet.`
+      details: `Final destination directory "${outputPath}" does not exist yet. This is OK if you haven't rendered the specs yet.`
     };
   } 
   
   return {
-    name: 'Output directory existence',
+    name: 'Final destination directory existence',
     success: true,
-    details: `Output directory "${outputPath}" exists`
+    details: `Final destination directory "${outputPath}" exists`
   };
 }
 
@@ -245,7 +259,7 @@ function findComplexHtmlPatterns(lines) {
 }
 
 /**
- * Check if HTML files in the output directory are being ignored by Git
+ * Check if HTML files in the final destination directory are being ignored by Git
  * @param {string} projectRoot - Root directory of the project
  * @param {string} normalizedPath - Normalized output path
  * @param {string} outputPath - Original output path
@@ -273,8 +287,8 @@ function checkHtmlFilesGitignore(projectRoot, normalizedPath, outputPath, releva
     name: 'Check if index.html files are gitignored',
     success: !isIndexHtmlIgnored,
     details: isIndexHtmlIgnored 
-      ? `index.html files in the output directory would be ignored by Git. This is problematic as they're crucial output files.`
-      : `index.html files in the output directory are properly tracked by Git.`
+      ? `index.html files in the final destination directory would be ignored by Git. This is problematic as they're crucial output files.`
+      : `index.html files in the final destination directory are properly tracked by Git.`
   });
   
   // If index.html is ignored but we couldn't find an explicit pattern, look for more complex patterns
@@ -295,22 +309,22 @@ function checkHtmlFilesGitignore(projectRoot, normalizedPath, outputPath, releva
 }
 
 /**
- * Check if output directory is being ignored by Git
+ * Check if final destination directory (from output_path) is being ignored by Git
  * @param {string} projectRoot - Root directory of the project
  * @param {string} normalizedPath - Normalized output path
  * @param {string} outputPath - Original output path
  * @param {string} dirName - Directory name from path
  * @param {Array} relevantLines - Relevant lines from .gitignore
- * @returns {Array} - Results for output directory gitignore check
+ * @returns {Array} - Results for final destination directory gitignore check
  */
 function checkOutputDirIgnorePatterns(projectRoot, normalizedPath, outputPath, dirName, relevantLines) {
   const dirIgnorePatterns = findOutputDirIgnorePatterns(relevantLines, normalizedPath, dirName);
   
   if (dirIgnorePatterns.length > 0) {
     return [{
-      name: 'Check if output directory is gitignored',
+      name: 'Check if final destination directory is gitignored',
       success: false,
-      details: `Found patterns in .gitignore that would ignore the output directory: ${dirIgnorePatterns.join(', ')}. Remove these entries to ensure generated content is tracked.`
+      details: `Found patterns in .gitignore that would ignore the final destination directory: ${dirIgnorePatterns.join(', ')}. Remove these entries to ensure generated content is tracked.`
     }];
   }
   
@@ -318,20 +332,21 @@ function checkOutputDirIgnorePatterns(projectRoot, normalizedPath, outputPath, d
   const isIgnored = isPathGitIgnored(projectRoot, normalizedPath);
   
   return [{
-    name: 'Check if output directory is gitignored',
+    name: 'Check if final destination directory is gitignored',
     success: !isIgnored,
     details: isIgnored 
-      ? `Output directory "${outputPath}" is being ignored by Git. This could be due to a complex pattern in .gitignore. Remove any entries that might affect this directory.`
-      : `Output directory "${outputPath}" is not being ignored by Git, which is good.`
+      ? `Final destination directory "${outputPath}" is being ignored by Git. This could be due to a complex pattern in .gitignore. Remove any entries that might affect this directory.`
+      : `Final destination directory "${outputPath}" is not being ignored by Git, which is good.`
   }];
 }
 
 /**
- * Check if the output directory is being ignored by Git
+ * Check if the final destination directory (from output_path in specs.json) is being ignored by Git
+ * This checks the directory where index.html is generated, NOT the temporary .cache directory
  * @param {string} projectRoot - Root directory of the project
  * @returns {Promise<Array>} - Array of check results
  */
-async function checkOutputDirGitIgnore(projectRoot) {
+async function checkDestinationGitIgnore(projectRoot) {
   const results = [];
   
   try {
@@ -369,7 +384,7 @@ async function checkOutputDirGitIgnore(projectRoot) {
     const relevantLines = getRelevantGitignoreLines(gitignoreContent);
     const dirName = path.basename(normalizedPath);
     
-    // Check output directory ignore patterns
+    // Check final destination directory ignore patterns
     const dirResults = checkOutputDirIgnorePatterns(
       projectRoot, normalizedPath, outputPath, dirName, relevantLines
     );
@@ -383,9 +398,9 @@ async function checkOutputDirGitIgnore(projectRoot) {
     
     return results;
   } catch (error) {
-    console.error('Error checking output directory gitignore status:', error);
+    console.error('Error checking final destination directory gitignore status:', error);
     return [{
-      name: 'Output directory gitignore check',
+      name: 'Final destination directory gitignore check',
       success: false,
       details: `Error: ${error.message}`
     }];
@@ -393,5 +408,5 @@ async function checkOutputDirGitIgnore(projectRoot) {
 }
 
 module.exports = {
-  checkOutputDirGitIgnore
+  checkDestinationGitIgnore
 };