spec-up-t 1.4.1-beta.2 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.4.1-beta.2",
+  "version": "1.4.1",
   "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/freeze-spec-data.js

@@ -44,3 +44,7 @@ const destFile = path.join(newVersionDir, 'index.html');
 fs.copyFileSync(sourceFile, destFile);
 
 Logger.success(`Created a freezed specification version in ${destFile}`);
+
+// Update the versions index.html to include the newly created version
+const createVersionsIndex = require('./pipeline/configuration/create-versions-index.js');
+createVersionsIndex(outputPath);

package/src/freeze.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * freeze.js
+ *
+ * Legacy wrapper to run the existing src/freeze-spec-data.js script.
+ * This file intentionally keeps logic minimal: it simply requires the
+ * implementation file so older tooling or CI jobs that call `freeze.js`
+ * continue to work without changing behaviour.
+ *
+ * Usage:
+ *   node freeze.js
+ * or make it executable and run:
+ *   ./freeze.js
+ *
+ * Rationale for keeping this file:
+ * - It provides a stable legacy entry point used by external consumers.
+ * - The real implementation remains in src/freeze-spec-data.js so maintenance
+ *   and tests remain focused there.
+ */
+
+const path = require('path');
+
+// The implementation `freeze-spec-data.js` now lives in the same `src` folder
+// as this wrapper, so require it directly from __dirname.
+const scriptPath = path.join(__dirname, 'freeze-spec-data.js');
+
+try {
+  // Require executes the implementation file. It is expected to run
+  // synchronously at top-level (the existing file performs its actions
+  // when loaded).
+  require(scriptPath);
+} catch (err) {
+  // Keep error reporting minimal and consistent with CLI usage.
+  // Use stderr for messages and exit with non-zero code on failure.
+  // This keeps behaviour predictable for callers.
+  // eslint-disable-next-line no-console
+  console.error('Failed to execute freeze script:', err && err.message ? err.message : err);
+  process.exitCode = 1;
+}

package/src/parsers/template-tag-parser.js

@@ -200,15 +200,22 @@ function parseTref(token) {
     displayText = `<span class='term-external-original-term term-original-term' title='original term'>${termName}</span>`;
   }
 
-  const termId = `term:${termName.replace(whitespace.oneOrMore, '-').toLowerCase()}`;
-  const primaryAliasId = aliases.length > 0 ? `term:${aliases[0].replace(whitespace.oneOrMore, '-').toLowerCase()}` : '';
-
-  // Handle cases where we have aliases
-  if (aliases.length > 0 && aliases[0] !== termName) {
-    return `<span data-original-term="${termName}" class="term-external" id="${termId}"><span title="Externally defined as ${termName}" id="${primaryAliasId}">${displayText}</span></span>`;
-  } else {
-    return `<span title="Externally also defined as ${termName}" data-original-term="${termName}" class="term-external" id="${termId}">${displayText}</span>`;
-  }
+  // Generate HTML spans for each term/alias combination, similar to parseDef
+  // This creates anchor points that can be referenced by [[ref: ...]] links
+  // token.info.args for tref is [externalSpec, term, alias1, alias2, ...]
+  // We need to create IDs for the term and all aliases (skip the externalSpec at index 0)
+  const termsAndAliases = [termName, ...aliases];
+
+  return termsAndAliases.reduce((acc, syn, index) => {
+    // Generate a unique term ID by normalizing the synonym: replace whitespace with hyphens and convert to lowercase
+    const termId = `term:${syn.replace(whitespace.oneOrMore, '-').toLowerCase()}`;
+    // Add title attribute to the innermost span (first in the array, which wraps the display text directly)
+    // This provides a tooltip showing which external term this alias refers to
+    const titleAttr = index === 0 && aliases.length > 0 ? ` title="Externally defined as ${termName}"` : '';
+    // Add class and data attributes only to the outermost span (last one created)
+    const outerAttrs = index === termsAndAliases.length - 1 ? ` data-original-term="${termName}" class="term-external"` : '';
+    return `<span id="${termId}"${outerAttrs}${titleAttr}>${acc}</span>`;
+  }, displayText);
 }
 
 /**
@@ -237,7 +244,7 @@ function processXTrefObject(xtref) {
 
   // Collect all aliases from parts after the term (index 1), trim and filter empties
   const allAliases = parts.slice(2).map(p => p.trim()).filter(Boolean);
-  
+
   // Initialize both tref and xref alias arrays
   xtrefObject.trefAliases = [];
   xtrefObject.xrefAliases = [];

package/src/pipeline/references/external-references-service.js

@@ -118,22 +118,24 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
     // Add xref terms to the allXTrefs structure
     // Mark them with source: 'xref' to distinguish from tref entries
     xrefTerms.forEach(xrefTerm => {
-      // Check if this term already exists (avoid duplicates)
+      // Check if this term already exists (match by externalSpec and term only)
+      // Don't filter by source because entries from markdown scanning don't have source field
       const existingIndex = allXTrefs.xtrefs.findIndex(existing =>
         existing.externalSpec === xrefTerm.externalSpec &&
-        existing.term === xrefTerm.term &&
-        existing.source === 'xref'
+        existing.term === xrefTerm.term
       );
 
       if (existingIndex >= 0) {
-        // Update existing entry
+        // Update existing entry - preserve the existing metadata but add/update content
         allXTrefs.xtrefs[existingIndex] = {
           ...allXTrefs.xtrefs[existingIndex],
-          ...xrefTerm,
+          content: xrefTerm.content,  // Update the content from fetched HTML
+          source: xrefTerm.source,     // Add source field
+          termId: xrefTerm.termId,     // Add termId if not present
           lastUpdated: new Date().toISOString()
         };
       } else {
-        // Add new entry
+        // Add new entry (this term wasn't referenced in the markdown)
         allXTrefs.xtrefs.push({
           ...xrefTerm,
           lastUpdated: new Date().toISOString()
@@ -179,28 +181,53 @@ function extractTermsFromHtml(externalSpec, html) {
       batch.each((index, termElement) => {
         try {
           const $termElement = $(termElement);
-          const termId = $termElement.attr('id');
           
-          // Skip elements without an id attribute or with invalid id format
-          if (!termId || !termId.includes('term:')) {
+          // The id can be on the dt element itself OR on span(s) inside it
+          // Some terms have multiple nested spans with different IDs (e.g., aliases)
+          // We need to extract ALL term IDs from the dt element
+          const termIds = [];
+          
+          // First check if dt itself has an id
+          const dtId = $termElement.attr('id');
+          if (dtId && dtId.includes('term:')) {
+            termIds.push(dtId.replace('term:', ''));
+          }
+          
+          // Then find all spans with ids that contain 'term:'
+          $termElement.find('span[id*="term:"]').each((i, span) => {
+            const spanId = $(span).attr('id');
+            if (spanId && spanId.includes('term:')) {
+              const termName = spanId.replace('term:', '');
+              if (!termIds.includes(termName)) {
+                termIds.push(termName);
+              }
+            }
+          });
+          
+          // Skip if no valid term IDs found
+          if (termIds.length === 0) {
             return;
           }
           
-          const termName = termId.replace('term:', '');
           const dd = $termElement.next('dd');
 
           if (dd.length > 0) {
-            // Create term object compatible with allXTrefs structure
-            const termObj = {
-              externalSpec: externalSpec,
-              term: termName,
-              content: $.html(dd), // Store the complete DD content
-              // Add metadata for consistency with tref structure
-              source: 'xref', // Distinguish from tref entries
-              termId: `term:${externalSpec}:${termName}`, // Fully qualified term ID
-            };
-
-            terms.push(termObj);
+            const ddContent = $.html(dd); // Store the complete DD content once
+            
+            // Create a term object for each ID found in this dt element
+            // This handles cases where one term definition has multiple aliases
+            termIds.forEach(termName => {
+              const termObj = {
+                externalSpec: externalSpec,
+                term: termName,
+                content: ddContent,
+                // Add metadata for consistency with tref structure
+                source: 'xref', // Distinguish from tref entries
+                termId: `term:${externalSpec}:${termName}`, // Fully qualified term ID
+              };
+
+              terms.push(termObj);
+            });
           }
         } catch (termError) {
           Logger.warn(`Error processing term in ${externalSpec}:`, termError.message);