spec-up-t 1.4.1-beta.3 → 1.5.0

package/src/install-from-boilerplate/config-scripts-keys.js

@@ -11,7 +11,7 @@ const configScriptsKeys = {
     "menu": "bash ./node_modules/spec-up-t/src/install-from-boilerplate/menu.sh",
     "addremovexrefsource": "node --no-warnings -e \"require('spec-up-t/src/add-remove-xref-source.js')\"",
     "configure": "node --no-warnings -e \"require('spec-up-t/src/configure.js')\"",
-    "healthCheck": "node --no-warnings -e \"require('spec-up-t/src/health-check.js')\"",
+    "healthCheck": "node --no-warnings ./node_modules/spec-up-t/src/health-check.js",
     "custom-update": "npm update && node -e \"require('spec-up-t/src/install-from-boilerplate/custom-update.js')\""
 };
 

package/src/markdown-it/README.md

@@ -46,19 +46,7 @@ Our extensions override default renderer rules and add custom inline parsing rul
 - Creates template tokens with parsed information
 - Provides a renderer rule to convert template tokens to HTML
 
-### 3. `link-enhancement.js`
-
-**Purpose**: Adds path-based attributes to links for CSS styling and JavaScript targeting.
-
-**Features**:
-
-- Extracts domain and path segments from URLs
-- Adds `path-0`, `path-1`, etc. attributes to anchor tags
-- Special handling for auto-detected links (linkify)
-
-**How it works**: Overrides `link_open` and `link_close` renderer rules.
-
-### 4. `definition-lists.js`
+### 3. `definition-lists.js`
 
 **Purpose**: Advanced processing of definition lists for terminology and reference management.
 
@@ -75,7 +63,7 @@ Our extensions override default renderer rules and add custom inline parsing rul
 - Uses helper functions to analyze token structure and content
 - Applies CSS classes based on term types and context
 
-### 5. `index.js`
+### 4. `index.js`
 
 **Purpose**: Main orchestrator that applies all enhancements in the correct order.
 

package/src/markdown-it/index.js

@@ -12,7 +12,6 @@
  * 
  * - TABLE ENHANCEMENT: Bootstrap styling and responsive wrappers
  * - TEMPLATE-TAG SYNTAX: Custom [[template-tag:args]] syntax processing
- * - LINK ENHANCEMENT: Path-based attributes for links
  * - DEFINITION LISTS: Advanced terminology and reference list handling
  * 
  * This modular approach makes the code more maintainable and easier to
@@ -22,7 +21,6 @@
 // Import all the specialized enhancement modules
 const applyTableEnhancements = require('./table-enhancement');
 const applyTemplateTagSyntax = require('./template-tag-syntax');
-const applyLinkEnhancements = require('./link-enhancement');
 const applyDefinitionListEnhancements = require('./definition-lists');
 
 /**
@@ -64,10 +62,7 @@ function applyMarkdownItExtensions(md, templates = []) {
   // 2. Template-tag syntax - should be applied early as other modules may depend on it
   applyTemplateTagSyntax(md, templates);
   
-  // 3. Link enhancements - independent, can be applied anytime
-  applyLinkEnhancements(md);
-  
-  // 4. Definition lists - depends on template-tag syntax for term type detection
+  // 3. Definition lists - depends on template-tag syntax for term type detection
   applyDefinitionListEnhancements(md);
   
   // The markdown-it instance is now fully enhanced and ready for use
@@ -79,5 +74,4 @@ module.exports = applyMarkdownItExtensions;
 // Also export individual modules for fine-grained control if needed
 module.exports.tableEnhancements = applyTableEnhancements;
 module.exports.templateTagSyntax = applyTemplateTagSyntax;
-module.exports.linkEnhancements = applyLinkEnhancements;
 module.exports.definitionLists = applyDefinitionListEnhancements;

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

@@ -14,6 +14,7 @@
 const { findExternalSpecByKey } = require('../pipeline/references/external-references-service.js');
 const { lookupXrefTerm } = require('../pipeline/rendering/render-utils.js');
 const { whitespace, htmlComments, contentCleaning, externalReferences } = require('../utils/regex-patterns');
+const Logger = require('../utils/logger.js');
 
 /**
  * Extracts the current file from token content for source tracking
@@ -135,11 +136,16 @@ function parseRef(globalState, primary) {
  * Uses primaryDisplayTerm concept: shows first alias if available, otherwise shows the term itself
  * @param {Object} config - Configuration containing external specs
  * @param {Object} token - The markdown-it token
- * @returns {string} HTML anchor element linking to external term
+ * @returns {string} HTML anchor element linking to external term or error span if unresolved
  */
 function parseXref(config, token) {
   const externalSpec = findExternalSpecByKey(config, token.info.args[0]);
-  const url = externalSpec?.gh_page || '#';
+  
+  // If external spec cannot be found, return error indicator
+  if (!externalSpec) {
+    return `<span class="no-xref-found-message" title="External spec '${token.info.args[0]}' not found in configuration">xref cannot be resolved</span>`;
+  }
+
   const termName = token.info.args[1];
   const aliases = token.info.args.slice(2).filter(Boolean); // Get all aliases after the term
   const term = termName.replace(whitespace.oneOrMore, '-').toLowerCase();
@@ -148,8 +154,11 @@ function parseXref(config, token) {
   // Determine the primary display term (first alias if available, otherwise original term)
   const primaryDisplayTerm = aliases.length > 0 ? aliases[0] : termName;
 
+  // Build the href attribute using the external spec's gh_page
+  const href = `${externalSpec.gh_page}#term:${term}`;
+
   // Build link attributes with both local and external href capabilities
-  let linkAttributes = `class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}" href="${url}#term:${term}"`;
+  let linkAttributes = `class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}" href="${href}"`;
 
   // Add tooltip content if term definition is available
   if (xrefTerm && xrefTerm.content) {
@@ -262,6 +271,13 @@ function processXTrefObject(xtref) {
     if (allAliases.length > 0) {
       xtrefObject.firstXrefAlias = allAliases[0];
     }
+    
+    // Log error if xref has more than one alias
+    // xref should only have 0 or 1 alias, unlike tref which supports multiple aliases
+    if (allAliases.length > 1) {
+      const extraAliases = allAliases.slice(1).join(', ');
+      Logger.error(`Invalid xref syntax: [[xref: ${xtrefObject.externalSpec}, ${xtrefObject.term}, ${allAliases.join(', ')}]] has ${allAliases.length} aliases. Only the first alias "${allAliases[0]}" will be used. Extra aliases ignored: ${extraAliases}.`);
+    }
   }
 
   return xtrefObject;

package/src/pipeline/postprocessing/definition-list-postprocessor.js

@@ -65,7 +65,8 @@ function sortDefinitionTermsInHtml(html) {
   });
 
   // Return the modified HTML
-  return dom.serialize();
+  // Extract only the body's innerHTML to avoid wrapping in <html><head></head><body> tags
+  return dom.window.document.body.innerHTML;
 }
 
 /**
@@ -340,7 +341,8 @@ function fixDefinitionListStructure(html) {
   }
 
   // Return the fixed HTML
-  return dom.serialize();
+  // Extract only the body's innerHTML to avoid wrapping in <html><head></head><body> tags
+  return dom.window.document.body.innerHTML;
 }
 
 module.exports = {

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

@@ -13,6 +13,7 @@ const fs = require('fs-extra');
 const readlineSync = require('readline-sync');
 
 const Logger = require('../../utils/logger');
+const messageCollector = require('../../utils/message-collector');
 const { shouldProcessFile } = require('../../utils/file-filter');
 const { getCurrentBranch } = require('../../utils/git-info');
 const { addNewXTrefsFromMarkdown, isXTrefInAnyFile } = require('./xtref-utils');
@@ -24,7 +25,8 @@ const { processXTrefObject } = require('../../parsers/template-tag-parser');
  * automated callers of `collectExternalReferences` continue to receive a fully rendered spec.
  */
 function renderSpecification() {
-    require('../../../index.js')({ nowatch: true });
+    // Pass skipClear to preserve messages from collectExternalReferences
+    require('../../../index.js')({ nowatch: true, skipClear: true });
 }
 
 /**
@@ -232,7 +234,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
     );
 
     fileContents.forEach((content, filename) => {
-        addNewXTrefsFromMarkdown(content, allXTrefs, filename, processXTrefObject);
+        addNewXTrefsFromMarkdown(content, allXTrefs, filename, processXTrefObject, externalSpecsRepos);
     });
 
     extendXTrefs(config, allXTrefs.xtrefs);
@@ -242,9 +244,17 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
 /**
  * Public entry point for the external reference collection stage.
  *
- * @param {{ pat?: string }} options - Optional overrides (GitHub PAT).
+ * @param {{ pat?: string, collectMessages?: boolean }} options - Optional overrides (GitHub PAT, message collection).
  */
 function collectExternalReferences(options = {}) {
+    // Start collecting messages if requested
+    const shouldCollectMessages = options.collectMessages !== false; // Collect by default
+    
+    if (shouldCollectMessages) {
+        messageCollector.clearMessages();
+        messageCollector.startCollecting('collectExternalReferences');
+    }
+
     const config = fs.readJsonSync('specs.json');
     const normalizedConfig = normalizeSpecConfiguration(config, {
         noSpecsMessage: 'No specs defined in specs.json. Nothing to collect.'
@@ -252,6 +262,10 @@ function collectExternalReferences(options = {}) {
 
     // Bail out immediately if the specs.json file lacks the required specs collection.
     if (!normalizedConfig) {
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages();
+        }
         return;
     }
 
@@ -268,7 +282,16 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'No external_specs array found on the first spec entry in specs.json. External reference collection is skipped.'
         );
-        renderSpecification();
+        
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return;
     }
 
@@ -277,7 +300,16 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'The external_specs array in specs.json is empty. Add external repositories to collect external references.'
         );
-        renderSpecification();
+        
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return;
     }
 
@@ -287,15 +319,40 @@ function collectExternalReferences(options = {}) {
     if (pipeline && typeof pipeline.then === 'function') {
         return pipeline
             .then(result => {
-                renderSpecification();
-                return result;
+                if (shouldCollectMessages) {
+                    messageCollector.stopCollecting();
+                    return messageCollector.saveMessages().then(path => {
+                        Logger.success(`Console messages saved to: ${path}`);
+                        renderSpecification();
+                        return result;
+                    });
+                } else {
+                    renderSpecification();
+                    return result;
+                }
             })
             .catch(error => {
                 Logger.error('Rendering failed after collecting external references.', error);
+                
+                if (shouldCollectMessages) {
+                    messageCollector.stopCollecting();
+                    messageCollector.saveMessages().catch(() => {
+                        // Silent fail on save error
+                    });
+                }
+                
                 throw error;
             });
     } else {
-        renderSpecification();
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return pipeline;
     }
 }

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

@@ -17,7 +17,7 @@ function validateReferences(references, definitions, render) {
     }
   );
   if (unresolvedRefs.length > 0) {
-    Logger.info('Unresolved References:', unresolvedRefs);
+    Logger.warn(`Unresolved References: ${unresolvedRefs.join(',')}`);
   }
 
   const danglingDefs = [];
@@ -38,7 +38,7 @@ function validateReferences(references, definitions, render) {
     }
   })
   if (danglingDefs.length > 0) {
-    Logger.info('Dangling Definitions:', danglingDefs);
+    Logger.warn(`Dangling Definitions: ${danglingDefs.join(',')}`);
   }
 }
 
@@ -117,6 +117,10 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
 
     // Add xref terms to the allXTrefs structure
     // Mark them with source: 'xref' to distinguish from tref entries
+    // Track how many terms were matched vs skipped for logging purposes
+    let matchedCount = 0;
+    let skippedCount = 0;
+
     xrefTerms.forEach(xrefTerm => {
       // 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
@@ -126,20 +130,54 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
       );
 
       if (existingIndex >= 0) {
+        // Get the existing entry to check if it's a tref
+        const existingXtref = allXTrefs.xtrefs[existingIndex];
+        
         // Update existing entry - preserve the existing metadata but add/update content
         allXTrefs.xtrefs[existingIndex] = {
-          ...allXTrefs.xtrefs[existingIndex],
+          ...existingXtref,
           content: xrefTerm.content,  // Update the content from fetched HTML
+          classes: xrefTerm.classes || [], // Update classes from dt element
           source: xrefTerm.source,     // Add source field
           termId: xrefTerm.termId,     // Add termId if not present
           lastUpdated: new Date().toISOString()
         };
+
+        // Check if this is a tref to an external tref (nested tref)
+        // A term with 'term-external' class means it's transcluded from another spec
+        const isExternalTref = xrefTerm.classes && xrefTerm.classes.includes('term-external');
+        const isTref = existingXtref.sourceFiles && existingXtref.sourceFiles.some(sf => sf.type === 'tref');
+        const isXref = existingXtref.sourceFiles && existingXtref.sourceFiles.some(sf => sf.type === 'xref');
+
+        if (isExternalTref && isTref) {
+          // Build a readable list of source files for the error message
+          const sourceFilesList = existingXtref.sourceFile 
+            ? existingXtref.sourceFile 
+            : (existingXtref.sourceFiles || []).map(sf => sf.file).join(', ');
+          
+          // Construct the external repository URL
+          const externalRepoUrl = existingXtref.ghPageUrl || existingXtref.repoUrl || `https://github.com/${existingXtref.owner}/${existingXtref.repo}`;
+          
+          Logger.error(`Origin: ${sourceFilesList} 👉 NESTED TREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec} is itself a tref (transcluded from another spec). This creates a chain of external references.`);
+        }
+
+        if (isExternalTref && isXref) {
+          // Build a readable list of source files for the warning message
+          const sourceFilesList = existingXtref.sourceFile 
+            ? existingXtref.sourceFile 
+            : (existingXtref.sourceFiles || []).map(sf => sf.file).join(', ');
+          
+          // Construct the external repository URL
+          const externalRepoUrl = existingXtref.ghPageUrl || existingXtref.repoUrl || `https://github.com/${existingXtref.owner}/${existingXtref.repo}`;
+          
+          Logger.error(`Origin: ${sourceFilesList} 👉 NESTED XREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec} is itself a tref (transcluded from another spec). This xref points to a term that is already transcluded from elsewhere, creating a chain of external references. (${externalRepoUrl})`);
+        }
+
+        matchedCount++;
       } else {
-        // Add new entry (this term wasn't referenced in the markdown)
-        allXTrefs.xtrefs.push({
-          ...xrefTerm,
-          lastUpdated: new Date().toISOString()
-        });
+        // Skip terms that are not referenced in the local markdown files
+        // This prevents bloating the xtrefs-data.json with unreferenced terms
+        skippedCount++;
       }
     });
 
@@ -150,7 +188,7 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
     const stringReadyForFileWrite = `const allXTrefs = ${allXTrefsStr};`;
     fs.writeFileSync(outputPathJS, stringReadyForFileWrite, 'utf8');
 
-    Logger.success(`Merged ${xrefTerms.length} xref terms into allXTrefs. Total entries: ${allXTrefs.xtrefs.length}`);
+    Logger.success(`Merged xref terms: ${matchedCount} matched, ${skippedCount} skipped (not referenced). Total entries: ${allXTrefs.xtrefs.length}`);
 
   } catch (error) {
     Logger.error('Error merging xref terms into allXTrefs:', error.message);
@@ -208,6 +246,12 @@ function extractTermsFromHtml(externalSpec, html) {
           if (termIds.length === 0) {
             return;
           }
+
+          // Extract classes from the <dt> element to determine if it's a local or external term.
+          // This helps identify if a tref to an external resource is itself a tref (term-external).
+          const dtClasses = $termElement.attr('class');
+          const classArray = dtClasses ? dtClasses.split(/\s+/).filter(Boolean) : [];
+          const termClasses = classArray.filter(cls => cls === 'term-local' || cls === 'term-external');
           
           const dd = $termElement.next('dd');
 
@@ -221,9 +265,10 @@ function extractTermsFromHtml(externalSpec, html) {
                 externalSpec: externalSpec,
                 term: termName,
                 content: ddContent,
+                classes: termClasses, // CSS classes from dt element (term-local or term-external)
                 // Add metadata for consistency with tref structure
                 source: 'xref', // Distinguish from tref entries
-                termId: `term:${externalSpec}:${termName}`, // Fully qualified term ID
+                termId: `term:${termName}`, // Term ID matches the actual HTML anchor format
               };
 
               terms.push(termObj);

package/src/pipeline/references/fetch-terms-from-index.js

@@ -12,6 +12,16 @@ const Logger = require('../../utils/logger');
 
 const CACHE_DIR = getPath('githubcache');
 
+/**
+ * Retrieves the latest commit hash for a specific file in a GitHub repository.
+ * 
+ * @param {string} token - GitHub API token for authentication
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {string} filePath - Path to the file within the repository
+ * @param {Object} headers - HTTP headers for the request
+ * @returns {Promise<string|null>} The commit SHA or null if not found
+ */
 async function getFileCommitHash(token, owner, repo, filePath, headers) {
     try {
         const normalizedPath = filePath.replace(/^\//, '');
@@ -31,6 +41,27 @@ async function getFileCommitHash(token, owner, repo, filePath, headers) {
     }
 }
 
+/**
+ * Fetches all term definitions from an external specification repository.
+ * Extracts terms from the generated index.html file and includes CSS classes
+ * to identify whether terms are local definitions or external references.
+ * 
+ * @param {string} token - GitHub API token for authentication
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {Object} [options={}] - Additional options
+ * @param {string} [options.ghPageUrl] - GitHub Pages URL for the repository
+ * @returns {Promise<Object|null>} Object containing:
+ *   - {number} timestamp - Unix timestamp when terms were fetched
+ *   - {string} repository - Full repository path (owner/repo)
+ *   - {Array<Object>} terms - Array of term objects, each containing:
+ *     - {string} term - The term identifier
+ *     - {string} definition - HTML definition content
+ *     - {Array<string>} classes - CSS classes from the dt element ('term-local' or 'term-external')
+ *   - {string|null} sha - Commit hash
+ *   - {string|null} avatarUrl - Avatar URL
+ *   - {string} outputFileName - Name of the cached file
+ */
 async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
     try {
         const headers = token ? { Authorization: `token ${token}` } : {};
@@ -118,6 +149,12 @@ async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
                 return;
             }
 
+            // Extract classes from the <dt> element to determine if it's a local or external term.
+            // This helps identify if a tref to an external resource is itself a tref (term-external)
+            // or a local definition (term-local).
+            const dtClasses = dt.className ? dt.className.split(/\s+/).filter(Boolean) : [];
+            const termClasses = dtClasses.filter(cls => cls === 'term-local' || cls === 'term-external');
+
             const definitions = [];
             let pointer = dt.nextElementSibling;
             while (pointer && pointer.tagName.toLowerCase() === 'dd') {
@@ -125,7 +162,11 @@ async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
                 pointer = pointer.nextElementSibling;
             }
 
-            terms.push({ term: termText, definition: definitions.join('\n') });
+            terms.push({ 
+                term: termText, 
+                definition: definitions.join('\n'),
+                classes: termClasses
+            });
         });
 
         const timestamp = Date.now();
@@ -163,6 +204,25 @@ async function fetchAllTermsFromIndex(token, owner, repo, options = {}) {
     }
 }
 
+/**
+ * Fetches a specific term definition from an external specification repository.
+ * This is a convenience wrapper around fetchAllTermsFromIndex that returns
+ * only a single matching term.
+ * 
+ * @param {string} token - GitHub API token for authentication
+ * @param {string} term - The specific term to fetch
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {string} termsDir - Terms directory (currently unused but kept for compatibility)
+ * @param {Object} [options={}] - Additional options
+ * @param {string} [options.ghPageUrl] - GitHub Pages URL for the repository
+ * @returns {Promise<Object|null>} Object containing:
+ *   - {string} term - The term identifier
+ *   - {string} content - HTML definition content
+ *   - {Array<string>} classes - CSS classes ('term-local' or 'term-external')
+ *   - {string|null} sha - Commit hash
+ *   - {Object} repository - Repository metadata
+ */
 async function fetchTermsFromIndex(token, term, owner, repo, termsDir, options = {}) {
     const allTermsData = await fetchAllTermsFromIndex(token, owner, repo, options);
     if (!allTermsData || !Array.isArray(allTermsData.terms)) {
@@ -179,6 +239,7 @@ async function fetchTermsFromIndex(token, term, owner, repo, termsDir, options =
     return {
         term: foundTerm.term,
         content: foundTerm.definition,
+        classes: foundTerm.classes || [],
         sha: allTermsData.sha,
         repository: {
             owner: {

package/src/pipeline/references/process-xtrefs-data.js

@@ -69,6 +69,40 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
                     xtref.commitHash = allTermsData.sha;
                     xtref.content = foundTerm.definition;
                     xtref.avatarUrl = allTermsData.avatarUrl;
+                    // Copy the classes array from the foundTerm to identify if this is a local or external term.
+                    // This helps determine if a tref to an external resource is itself a tref (term-external).
+                    xtref.classes = foundTerm.classes || [];
+
+                    // Check if this is a tref to an external tref (nested tref)
+                    // A term with 'term-external' class means it's transcluded from another spec
+                    const isExternalTref = foundTerm.classes && foundTerm.classes.includes('term-external');
+                    const isTref = xtref.sourceFiles && xtref.sourceFiles.some(sf => sf.type === 'tref');
+                    const isXref = xtref.sourceFiles && xtref.sourceFiles.some(sf => sf.type === 'xref');
+
+                    if (isExternalTref && isTref) {
+                        // Build a readable list of source files for the error message
+                        const sourceFilesList = xtref.sourceFile 
+                            ? xtref.sourceFile 
+                            : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
+                        
+                        // Construct the external repository URL
+                        const externalRepoUrl = xtref.ghPageUrl || xtref.repoUrl || `https://github.com/${xtref.owner}/${xtref.repo}`;
+                        
+                        Logger.error(`Origin: ${sourceFilesList} 👉 NESTED TREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec} is itself a tref (transcluded from another spec). This creates a chain of external references.`);
+                    }
+
+                    if (isExternalTref && isXref) {
+                        // Build a readable list of source files for the warning message
+                        const sourceFilesList = xtref.sourceFile 
+                            ? xtref.sourceFile 
+                            : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
+                        
+                        // Construct the external repository URL
+                        const externalRepoUrl = xtref.ghPageUrl || xtref.repoUrl || `https://github.com/${xtref.owner}/${xtref.repo}`;
+                        
+                        Logger.error(`Origin: ${sourceFilesList} 👉 NESTED XREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec} is itself a tref (transcluded from another spec). This xref points to a term that is already transcluded from elsewhere, creating a chain of external references. (${externalRepoUrl})`);
+                    }
+
                     Logger.success(`Match found for term: ${xtref.term} in ${xtref.externalSpec}`);
                 } else {
                     xtref.commitHash = 'not found';

package/src/pipeline/references/xtref-utils.js

@@ -7,6 +7,7 @@
  */
 
 const { externalReferences, utils } = require('../../utils/regex-patterns');
+const Logger = require('../../utils/logger');
 
 /**
  * Checks if a specific xtref is present in the markdown content.
@@ -43,13 +44,30 @@ function isXTrefInAnyFile(xtref, fileContents) {
  * @param {object} xtrefObject - Pre-parsed xtref object from template-tag-parser
  * @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection
  * @param {string|null} filename - Originating filename for bookkeeping
+ * @param {Array<object>|null} externalSpecs - Array of external_specs from specs.json for validation
  * @returns {{ xtrefs: Array<object> }} Updated reference collection
  */
-function addXtrefToCollection(xtrefObject, allXTrefs, filename = null) {
+function addXtrefToCollection(xtrefObject, allXTrefs, filename = null, externalSpecs = null) {
     const referenceType = xtrefObject.referenceType;
     const cleanXTrefObj = { ...xtrefObject };
     delete cleanXTrefObj.referenceType;
 
+    // Validate that the external spec exists in specs.json configuration
+    if (externalSpecs && Array.isArray(externalSpecs)) {
+        const externalSpecExists = externalSpecs.some(
+            spec => spec.external_spec === cleanXTrefObj.externalSpec
+        );
+        
+        if (!externalSpecExists) {
+            const availableSpecs = externalSpecs.map(s => s.external_spec).join(', ');
+            Logger.error(
+                `External spec "${cleanXTrefObj.externalSpec}" not found in specs.json configuration. ` +
+                `Available external specs: ${availableSpecs}. ` +
+                `Check [[${referenceType}: ${cleanXTrefObj.externalSpec}, ${cleanXTrefObj.term}]] in ${filename || 'unknown file'}`
+            );
+        }
+    }
+
     const existingIndex = allXTrefs?.xtrefs?.findIndex(existingXTref =>
         existingXTref.term === cleanXTrefObj.term &&
         existingXTref.externalSpec === cleanXTrefObj.externalSpec
@@ -135,9 +153,10 @@ function addXtrefToCollection(xtrefObject, allXTrefs, filename = null) {
  * @param {{ xtrefs: Array<object> }} allXTrefs - Aggregated reference collection.
  * @param {string|null} filename - Originating filename for bookkeeping.
  * @param {function} processXTrefObject - Parsing function for xtref strings.
+ * @param {Array<object>|null} externalSpecs - Array of external_specs from specs.json for validation.
  * @returns {{ xtrefs: Array<object> }} Updated reference collection.
  */
-function addNewXTrefsFromMarkdown(markdownContent, allXTrefs, filename = null, processXTrefObject) {
+function addNewXTrefsFromMarkdown(markdownContent, allXTrefs, filename = null, processXTrefObject, externalSpecs = null) {
     if (!processXTrefObject) {
         throw new Error('processXTrefObject function is required. Import from template-tag-parser.');
     }
@@ -152,7 +171,7 @@ function addNewXTrefsFromMarkdown(markdownContent, allXTrefs, filename = null, p
 
     xtrefs.forEach(rawXtref => {
         const xtrefObject = processXTrefObject(rawXtref);
-        addXtrefToCollection(xtrefObject, allXTrefs, filename);
+        addXtrefToCollection(xtrefObject, allXTrefs, filename, externalSpecs);
     });
 
     return allXTrefs;

package/src/pipeline/rendering/render-spec-document.js

@@ -111,7 +111,6 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
       assetsHead: assets.head,
       assetsBody: assets.body,
       assetsSvg: assets.svg,
-      features: Object.keys(features).join(' '),
       externalReferences: '', // No longer inject DOM HTML - xrefs are in allXTrefs
       xtrefsData: createScriptElementWithXTrefDataForEmbeddingInHtml(),
       specLogo: spec.logo,