spec-up-t 1.2.9 → 1.3.0

package/assets/js/insert-trefs.js

@@ -27,11 +27,11 @@ function insertTrefs(allXTrefs) {
        * @type {Array<{element: Element, textContent: string, dt: Element, parent: Element}>}
        */
       const allTerms = [];
-      document.querySelectorAll('dt span.transcluded-xref-term').forEach(termElement => {
-         const textContent = Array.from(termElement.childNodes)
-            .filter(node => node.nodeType === Node.TEXT_NODE)
-            .map(node => node.textContent.trim())
-            .join('');
+
+      document.querySelectorAll('dl.terms-and-definitions-list dt span.transcluded-xref-term').forEach((termElement) => {
+         // Get the full text content including any nested spans (for aliases) of a term (dt)
+         // In case of `[[tref:toip1, agency, ag]]`, this will return `agency`
+         const textContent = termElement.textContent.trim();
 
          // Find the dt element once outside the loop
          const dt = termElement.closest('dt');
@@ -68,7 +68,7 @@ function insertTrefs(allXTrefs) {
 
          // Find the first matching xref to avoid duplicates
          const xref = xtrefsData.xtrefs.find(x => x.term === textContent);
-
+         
          // Create a DocumentFragment to hold all new elements for this term
          const fragment = document.createDocumentFragment();
 
@@ -93,16 +93,22 @@ function insertTrefs(allXTrefs) {
             metaInfoEl.innerHTML = md.render(metaInfo);
             fragment.appendChild(metaInfoEl);
 
-            // Clean up markdown content
+            // Clean up the markdown content in the term definition
+            // Part A: clean up via regex
             let content = xref.content
-               .replace(/\[\[def:[^\]]*?\]\]/g, '') // Remove [[def: ...]] patterns regardless of trailing chars
                .split('\n')
                .map(line => line.replace(/^\s*~\s*/, '')) // Remove leading ~ and spaces
                .join('\n')
-               .replace(/\[\[ref:/g, '') // Remove [[ref: ...]]
                .replace(/\]\]/g, '');
 
-            // Parse the rendered HTML to check for dd elements
+            // Clean up the markdown content in the term definition
+            // Part B: Remove all <a> elements from the content via a temporary div and DOM manipulation
+            const tempDivForLinks = document.createElement('div');
+            tempDivForLinks.innerHTML = md.render(content);
+            tempDivForLinks.querySelectorAll('a').forEach(a => a.replaceWith(...a.childNodes));
+            content = tempDivForLinks.innerHTML;
+
+            // Parse the rendered HTML to check for dd elements. xref.content is a string that contains HTML, in the form of <dd>...</dd>'s
             const tempDiv = document.createElement('div');
             tempDiv.innerHTML = md.render(content);
 
@@ -119,14 +125,17 @@ function insertTrefs(allXTrefs) {
                   fragment.appendChild(clonedDD);
                });
             } else {
-               // No dd elements found, create one to hold the content
+               /*
+                  No dd elements found, create one to hold the conten. Explanation: this is the content in case nothing was found:
+                  `"content": "This term was not found in the external repository"`
+               */
                const contentEl = document.createElement('dd');
                contentEl.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded');
                contentEl.innerHTML = tempDiv.innerHTML;
                fragment.appendChild(contentEl);
             }
          } else {
-            // Handle case where xref is not found
+            // When the [[tref]] is not valid, for example `[[tref: transferable, transferable]]`, where `transferable` is not an external repo in specs.json
             metaInfoEl.innerHTML = md.render(`
 | Property | Value |
 | -------- | ----- |
@@ -138,7 +147,7 @@ function insertTrefs(allXTrefs) {
 
             // Create not found message
             const notFoundEl = document.createElement('dd');
-            notFoundEl.classList.add('transcluded-xref-term', 'transcluded-xref-term-embedded', 'last-dd');
+
             notFoundEl.innerHTML = '<p>This term was not found in the external repository.</p>';
             fragment.appendChild(notFoundEl);
          }
@@ -160,28 +169,20 @@ function insertTrefs(allXTrefs) {
             const { dt, parent, fragment } = change;
             parent.insertBefore(fragment, dt.nextSibling);
          });
-         
+
          // Dispatch a custom event when all DOM modifications are complete
          // This allows other scripts to know exactly when our work is done
          /**
           * Dispatches a custom event to signal that trefs insertion is complete
           * @fires trefs-inserted
           */
-         document.dispatchEvent(new CustomEvent('trefs-inserted', { 
-            detail: { count: domChanges.length } 
+         document.dispatchEvent(new CustomEvent('trefs-inserted', {
+            detail: { count: domChanges.length }
          }));
       });
    }
 
-   if (allXTrefs?.xtrefs) {
-      processTerms(allXTrefs);
-   } else {
-      console.error('allXTrefs is undefined or missing xtrefs property');
-      // Dispatch event even when there are no xrefs, so waiting code knows we're done
-      document.dispatchEvent(new CustomEvent('trefs-inserted', { 
-         detail: { count: 0, error: 'Missing xtrefs data' } 
-      }));
-   }
+   processTerms(allXTrefs);
 }
 
 /**
@@ -231,11 +232,14 @@ function initializeOnTrefsInserted(initCallback) {
  * @listens DOMContentLoaded
  */
 document.addEventListener('DOMContentLoaded', () => {
-   // Check if allXTrefs is defined in the global scope
-   if (typeof allXTrefs !== 'undefined') {
+   if (typeof allXTrefs !== 'undefined' && allXTrefs?.xtrefs) {
       insertTrefs(allXTrefs);
    } else {
-      console.warn('allXTrefs is not available in the global scope. Transcluded references will not be inserted.');
+      console.error('allXTrefs is undefined or missing xtrefs property');
+      // Dispatch event even when there are no xrefs, so waiting code knows we're done
+      document.dispatchEvent(new CustomEvent('trefs-inserted', {
+         detail: { count: 0, error: 'Missing xtrefs data' }
+      }));
    }
 });
 

package/config/asset-map.json

@@ -27,6 +27,7 @@
       "assets/css/add-bootstrap-classes-to-images.css",
       "assets/css/horizontal-scroll-hint.css",
       "assets/css/highlight-heading-plus-sibling-nodes.css",
+      "assets/css/counter.css",
       "assets/css/index.css"
     ],
     "js": [

package/index.js

@@ -38,6 +38,7 @@ module.exports = async function (options = {}) {
 
     const { fixMarkdownFiles } = require('./src/fix-markdown-files.js');
     const { processEscapedTags, restoreEscapedTags } = require('./src/escape-mechanism.js');
+    const { sortDefinitionTermsInHtml, fixDefinitionListStructure } = require('./src/html-dom-processor.js');
 
     let template = fs.readFileSync(path.join(modulePath, 'templates/template.html'), 'utf8');
     let assets = fs.readJsonSync(modulePath + '/config/asset-map.json');
@@ -71,7 +72,13 @@ module.exports = async function (options = {}) {
       linkify: true,
       typographer: true
     })
+      /*
+        Configures a Markdown-it plugin by passing it an array of extension objects, each responsible for handling specific custom syntax in Markdown documents.
+      */
       .use(require('./src/markdown-it-extensions.js'), [
+        /*
+          The first extension (= the first configuration object = the first element of the array) focuses on terminology-related constructs, using a filter to match types against a regular expression (terminologyRegex).
+        */
         {
           filter: type => type.match(terminologyRegex),
           parse(token, type, primary) {
@@ -92,7 +99,20 @@ module.exports = async function (options = {}) {
               href="${url}#term:${term}">${token.info.args[1]}</a>`;
             }
             else if (type === 'tref') {
-              return `<span class="transcluded-xref-term" id="term:${token.info.args[1]}">${token.info.args[1]}</span>`;
+              // Support tref with optional alias: [[tref: spec, term, alias]]
+              const termName = token.info.args[1];
+              const alias = token.info.args[2]; // Optional alias
+              
+              // Create IDs for both the original term and the alias to enable referencing by either
+              const termId = `term:${termName.replace(spaceRegex, '-').toLowerCase()}`;
+              const aliasId = alias ? `term:${alias.replace(spaceRegex, '-').toLowerCase()}` : '';
+              
+              // Return the term structure similar to def, so it can be processed by markdown-it's definition list parser
+              if (aliasId && alias !== termName) {
+                return `<span class="transcluded-xref-term" id="${termId}"><span id="${aliasId}">${termName}</span></span>`;
+              } else {
+                return `<span class="transcluded-xref-term" id="${termId}">${termName}</span>`;
+              }
             }
             else {
               references.push(primary);
@@ -100,6 +120,9 @@ module.exports = async function (options = {}) {
             }
           }
         },
+        /*        
+          The second extension is designed for handling specification references.
+        */
         {
           filter: type => type.match(specNameRegex),
           parse(token, type, name) {
@@ -174,7 +197,7 @@ module.exports = async function (options = {}) {
       .use(require('@traptitech/markdown-it-katex'))
 
     const katexRules = ['math_block', 'math_inline'];
-    const replacerRegex = /\[\[\s*([^\s\[\]:]+):?\s*([^\]\n]+)?\]\]/img;
+    const replacerRegex = /\[\[\s*([^\s[\]:]+):?\s*([^\]\n]+)?\]\]/img;
     const replacerArgsRegex = /\s*,+\s*/;
     const replacers = [
       {
@@ -183,29 +206,6 @@ module.exports = async function (options = {}) {
           if (!path) return '';
           return fs.readFileSync(path, 'utf8');
         }
-      },
-
-      /**
-       * Custom replacer for tref tags that converts them directly to HTML definition term elements.
-       * 
-       * This is a critical part of our solution for fixing transcluded terms in definition lists.
-       * When a [[tref:spec,term]] tag is found in the markdown, this replacer transforms it into
-       * a proper <dt> element with the appropriate structure before the markdown parser processes it.
-       * 
-       * By directly generating the HTML structure (instead of letting the markdown-it parser
-       * handle it later), we prevent the issue where transcluded terms break the definition list.
-       * 
-       * @param {string} originalMatch - The original [[tref:spec,term]] tag found in the markdown
-       * @param {string} type - The tag type ('tref')
-       * @param {string} spec - The specification identifier (e.g., 'wot-1')
-       * @param {string} term - The term to transclude (e.g., 'DAR')
-       * @returns {string} - HTML representation of the term as a dt element
-       */
-      {
-        test: 'tref',
-        transform: function (originalMatch, type, spec, term) {
-          return `<dt class="transcluded-xref-term"><span class="transcluded-xref-term" id="term:${term.replace(/\s+/g, '-').toLowerCase()}">${term}</span></dt>`;
-        }
       }
     ];
 
@@ -295,208 +295,6 @@ module.exports = async function (options = {}) {
       throw Error("katex distribution could not be located");
     }
 
-    function sortDefinitionTermsInHtml(html) {
-      const { JSDOM } = require('jsdom');
-      const dom = new JSDOM(html);
-      const document = dom.window.document;
-
-      // Find the terms and definitions list
-      const dlElement = document.querySelector('.terms-and-definitions-list');
-      if (!dlElement) return html; // If not found, return the original HTML
-
-      // Collect all dt/dd pairs
-      const pairs = [];
-      let currentDt = null;
-      let currentDds = [];
-
-      // Process each child of the dl element
-      Array.from(dlElement.children).forEach(child => {
-        if (child.tagName === 'DT') {
-          // If we already have a dt, save the current pair
-          if (currentDt) {
-            pairs.push({
-              dt: currentDt,
-              dds: [...currentDds],
-              text: currentDt.textContent.trim().toLowerCase() // Use lowercase for sorting
-            });
-            currentDds = []; // Reset dds for the next dt
-          }
-          currentDt = child;
-        } else if (child.tagName === 'DD' && currentDt) {
-          currentDds.push(child);
-        }
-      });
-
-      // Add the last pair if exists
-      if (currentDt) {
-        pairs.push({
-          dt: currentDt,
-          dds: [...currentDds],
-          text: currentDt.textContent.trim().toLowerCase()
-        });
-      }
-
-      // Sort pairs case-insensitively
-      pairs.sort((a, b) => a.text.localeCompare(b.text));
-
-      // Clear the dl element
-      while (dlElement.firstChild) {
-        dlElement.removeChild(dlElement.firstChild);
-      }
-
-      // Re-append elements in sorted order
-      pairs.forEach(pair => {
-        dlElement.appendChild(pair.dt);
-        pair.dds.forEach(dd => {
-          dlElement.appendChild(dd);
-        });
-      });
-
-      // Return the modified HTML
-      return dom.serialize();
-    }
-
-    // Function to fix broken definition list structures
-    /**
-     * This function repairs broken definition list (dl) structures in the HTML output.
-     * Specifically, it addresses the issue where transcluded terms (tref tags) break
-     * out of the definition list, creating separate lists instead of a continuous one.
-     * 
-     * The strategy:
-     * 1. Find all definition lists (dl elements) in the document
-     * 2. Use the dl with class 'terms-and-definitions-list' as the main/target list
-     * 3. Process each subsequent node after the this main dl:
-     *    - If another dl is found, merge all its children into the main dl
-     *    - If a standalone dt is found, move it into the main dl
-     *    - Remove any empty paragraphs that might be breaking the list continuity
-     * 
-     * This ensures all terms appear in one continuous definition list,
-     * regardless of how they were originally rendered in the markdown.
-     * 
-     * @param {string} html - The HTML content to fix
-     * @returns {string} - The fixed HTML content with merged definition lists
-     */
-    function fixDefinitionListStructure(html) {
-      const { JSDOM } = require('jsdom');
-      const dom = new JSDOM(html);
-      const document = dom.window.document;
-
-      // Find all dl elements first
-      const allDls = Array.from(document.querySelectorAll('dl'));
-
-      // Then filter to find the one with the terms-and-definitions-list class
-      const dlElements = allDls.filter(dl => {
-        return dl?.classList?.contains('terms-and-definitions-list');
-      });
-
-      // Find any transcluded term dt elements anywhere in the document
-      const transcludedTerms = document.querySelectorAll('dt.transcluded-xref-term');
-
-      let mainDl = null;
-
-      // If we have an existing dl with the terms-and-definitions-list class, use it
-      if (dlElements.length > 0) {
-        mainDl = dlElements[0]; // Use the first one
-      }
-      // If we have transcluded terms but no main dl, we need to create one
-      else if (transcludedTerms.length > 0) {
-        // Create a new dl element with the right class
-        mainDl = document.createElement('dl');
-        mainDl.className = 'terms-and-definitions-list';
-
-        // Look for the marker
-        const marker = document.getElementById('terminology-section-start');
-
-        if (marker) {
-          // Insert the new dl right after the marker
-          if (marker.nextSibling) {
-            marker.parentNode.insertBefore(mainDl, marker.nextSibling);
-          } else {
-            marker.parentNode.appendChild(mainDl);
-          }
-        } else {
-          // Fallback to the original approach if marker isn't found
-          const firstTerm = transcludedTerms[0];
-          const insertPoint = firstTerm.parentNode;
-          insertPoint.parentNode.insertBefore(mainDl, insertPoint);
-        }
-      }
-
-      // Safety check - if we still don't have a mainDl, exit early to avoid null reference errors
-      if (!mainDl) {
-        return html; // Return the original HTML without modifications
-      }
-
-      // Now process all transcluded terms and other dt elements
-      transcludedTerms.forEach(dt => {
-        // Check if this dt is not already inside our main dl
-        if (dt.parentElement !== mainDl) {
-          // Move it into the main dl
-          const dtClone = dt.cloneNode(true);
-          mainDl.appendChild(dtClone);
-          dt.parentNode.removeChild(dt);
-        }
-      });
-
-      // First special case - handle transcluded-xref-term dt that comes BEFORE the main dl
-      const transcludedTermsBeforeMainDl = document.querySelectorAll('dt.transcluded-xref-term');
-
-      // Special handling for transcluded terms that appear BEFORE the main dl
-      transcludedTermsBeforeMainDl.forEach(dt => {
-        // Check if this dt is not already inside our main list
-        if (dt.parentElement !== mainDl) {
-          // This is a dt outside our main list - move it into the main dl
-          const dtClone = dt.cloneNode(true);
-          mainDl.appendChild(dtClone);
-          dt.parentNode.removeChild(dt);
-        }
-      });
-
-      // Remove any empty dt elements that may exist
-      const emptyDts = mainDl.querySelectorAll('dt:empty');
-      emptyDts.forEach(emptyDt => {
-        emptyDt.parentNode.removeChild(emptyDt);
-      });
-
-      // Process all subsequent content after the main dl
-      let currentNode = mainDl.nextSibling;
-
-      // Process all subsequent content
-      while (currentNode) {
-        // Save the next node before potentially modifying the DOM
-        const nextNode = currentNode.nextSibling;
-
-        // Handle different node types
-        if (currentNode.nodeType === 1) { // 1 = Element node
-          if (currentNode.tagName === 'DL') {
-            // Found another definition list - move all its children to the main dl
-            while (currentNode.firstChild) {
-              mainDl.appendChild(currentNode.firstChild);
-            }
-            // Remove the now-empty dl element
-            currentNode.parentNode.removeChild(currentNode);
-          }
-          else if (currentNode.tagName === 'DT') {
-            // Found a standalone dt - move it into the main dl
-            const dtClone = currentNode.cloneNode(true);
-            mainDl.appendChild(dtClone);
-            currentNode.parentNode.removeChild(currentNode);
-          }
-          else if (currentNode.tagName === 'P' &&
-            (!currentNode.textContent || currentNode.textContent.trim() === '')) {
-            // Remove empty paragraphs - these break the list structure
-            currentNode.parentNode.removeChild(currentNode);
-          }
-        }
-
-        // Move to the next node we saved earlier
-        currentNode = nextNode;
-      }
-
-      // Return the fixed HTML
-      return dom.serialize();
-    }
-
     async function render(spec, assets) {
       try {
         noticeTitles = {};
@@ -507,6 +305,13 @@ module.exports = async function (options = {}) {
           return template.replace(/\${(.*?)}/g, (match, p1) => variables[p1.trim()]);
         }
 
+        // Add current date in 'DD Month YYYY' format for template injection
+        const date = new Date();
+        const day = String(date.getDate()).padStart(2, '0');
+        const month = date.toLocaleString('en-US', { month: 'long' });
+        const year = date.getFullYear();
+        const currentDate = `${day} ${month} ${year}`;
+
         const docs = await Promise.all(
           (spec.markdown_paths || ['spec.md']).map(_path =>
             fs.readFile(spec.spec_directory + _path, 'utf8')
@@ -572,6 +377,7 @@ module.exports = async function (options = {}) {
           specLogoLink: spec.logo_link,
           spec: JSON.stringify(spec),
           externalSpecsList: externalSpecsList,
+          currentDate: currentDate
         });
 
         const outputPath = path.join(spec.destination, 'index.html');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "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": {
@@ -28,6 +28,7 @@
     "axios": "^1.7.7",
     "dedent": "^1.5.3",
     "diff": "^7.0.0",
+    "docx": "^8.5.0",
     "dotenv": "^16.4.7",
     "find-pkg-dir": "^2.0.0",
     "fs-extra": "^11.3.0",
@@ -67,7 +68,8 @@
     "braces": ">=3.0.3"
   },
   "devDependencies": {
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^30.0.5"
   },
   "scripts": {
     "test": "jest",

package/sonar-project.properties

@@ -0,0 +1,7 @@
+# Temporarily disabled for Automatic Analysis
+# sonar.projectKey=blockchainbird_spec-up-t
+# sonar.organization=blockchainbird
+# sonar.host.url=https://sonarcloud.io
+# sonar.token=SONAR_TOKEN
+# sonar.exclusions=assets/compiled/refs.json
+# sonar.cpd.exclusions=**/*.test.js

package/src/collect-external-references.js

@@ -54,26 +54,37 @@ const readlineSync = require('readline-sync');
  * @returns {boolean} True if the xtref is found in the content
  */
 function isXTrefInMarkdown(xtref, markdownContent) {
-    const regex = new RegExp(`\\[\\[(?:x|t)ref:${xtref.externalSpec},\\s*${xtref.term}\\]\\]`, 'g');
-    return regex.test(markdownContent);
+    // Escape special regex characters in externalSpec and term
+    const escapedSpec = xtref.externalSpec.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+    const escapedTerm = xtref.term.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+    
+    // Check for both the term and with any alias (accounting for spaces)
+    const regexTerm = new RegExp(`\\[\\[(?:x|t)ref:\\s*${escapedSpec},\\s*${escapedTerm}(?:,\\s*[^\\]]+)?\\]\\]`, 'g');
+    return regexTerm.test(markdownContent);
 }
 
 /**
  * Helper function to process an XTref string and return an object.
  * 
  * @param {string} xtref - The xtref string to process
- * @returns {Object} An object with externalSpec and term properties
+ * @returns {Object} An object with externalSpec, term, and optional alias properties
  */
 function processXTref(xtref) {
-    let [externalSpec, term] = xtref
+    const parts = xtref
         .replace(/\[\[(?:xref|tref):/, '')
         .replace(/\]\]/, '')
         .trim()
-        .split(/,/, 2);
+        .split(/,/);
+    
     const xtrefObject = {
-        externalSpec: externalSpec.trim(),
-        term: term.trim()
+        externalSpec: parts[0].trim(),
+        term: parts[1].trim()
     };
+    
+    // Add alias if provided (third parameter)
+    if (parts.length > 2 && parts[2].trim()) {
+        xtrefObject.alias = parts[2].trim();
+    }
 
     return xtrefObject;
 }
@@ -129,6 +140,7 @@ function extendXTrefs(config, xtrefs) {
                     xtref.owner = urlParts[1];
                     xtref.repo = urlParts[2];
                     xtref.avatarUrl = repo.avatar_url;
+                    xtref.ghPageUrl = repo.gh_page; // Add GitHub Pages URL
                 }
             });
 
@@ -149,9 +161,8 @@ function extendXTrefs(config, xtrefs) {
  * 
  * @param {Object} config - The configuration object from specs.json
  * @param {string} GITHUB_API_TOKEN - The GitHub API token
- * @param {Object} options - Configuration options
  */
-function processExternalReferences(config, GITHUB_API_TOKEN, options) {
+function processExternalReferences(config, GITHUB_API_TOKEN) {
     const { processXTrefsData } = require('./collectExternalReferences/processXTrefsData.js');
     const { doesUrlExist } = require('./utils/doesUrlExist.js');
     const externalSpecsRepos = config.specs[0].external_specs;
@@ -257,7 +268,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN, options) {
     //     }
     // ]
     
-    processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, outputPathJS, outputPathJSTimeStamped, options);
+    processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, outputPathJS, outputPathJSTimeStamped);
 }
 
 /**
@@ -320,7 +331,7 @@ function collectExternalReferences(options = {}) {
             return;
         }
     } else {
-        processExternalReferences(config, GITHUB_API_TOKEN, options);
+        processExternalReferences(config, GITHUB_API_TOKEN);
     }
 }