spec-up-t 1.4.1 → 1.6.0-beta.1

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

@@ -17,7 +17,11 @@ function validateReferences(references, definitions, render) {
     }
   );
   if (unresolvedRefs.length > 0) {
-    Logger.info('Unresolved References:', unresolvedRefs);
+    Logger.warn(`Unresolved References: ${unresolvedRefs.join(',')}`, {
+      context: 'These terms are referenced in your spec but not defined',
+      hint: 'Add [[def: term]] definitions for these terms in your terminology files, or check for typos in [[ref: term]] references',
+      details: `Count: ${unresolvedRefs.length} unresolved term(s)`
+    });
   }
 
   const danglingDefs = [];
@@ -38,7 +42,11 @@ function validateReferences(references, definitions, render) {
     }
   })
   if (danglingDefs.length > 0) {
-    Logger.info('Dangling Definitions:', danglingDefs);
+    Logger.warn(`Dangling Definitions: ${danglingDefs.join(',')}`, {
+      context: 'These terms are defined but never referenced in your spec',
+      hint: 'Add [[ref: term]] references where needed.',
+      details: `Count: ${danglingDefs.length} unused definition(s)`
+    });
   }
 }
 
@@ -71,7 +79,11 @@ async function fetchExternalSpecs(spec) {
         const msg = f.error.response
           ? `HTTP ${f.error.response.status} for ${f.url}`
           : `Network error for ${f.url}: ${f.error.message}`;
-        Logger.error("External spec fetch failed:", msg);
+        Logger.error("External spec fetch failed", {
+          context: `Attempting to fetch external terminology from: ${f.url}`,
+          hint: 'Verify the URL is correct in specs.json under external_specs[].gh_page. Ensure the external spec has published their GitHub Pages site',
+          details: msg
+        });
       });
     }
 
@@ -93,7 +105,11 @@ async function fetchExternalSpecs(spec) {
 
     return extractedTerms;
   } catch (e) {
-    Logger.error("Unexpected error in fetchExternalSpecs:", e);
+    Logger.error("Unexpected error in fetchExternalSpecs", {
+      context: 'Failed while fetching terms from external specifications',
+      hint: 'Check your internet connection and verify all external_specs URLs in specs.json are valid. Run with GITHUB_PAT set if accessing private repos',
+      details: e.message
+    });
     return [];
   }
 }
@@ -117,6 +133,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 +146,62 @@ 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(`NESTED TREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec}`, {
+            context: `Origin: ${sourceFilesList} - This term is itself transcluded from another spec`,
+            hint: 'Avoid chaining external references (tref → tref). Reference the original source spec directly, or define the term locally in your spec',
+            details: `This creates a complex dependency chain. Repository: ${externalRepoUrl}`
+          });
+        }
+
+        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(`NESTED XREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec}`, {
+            context: `Origin: ${sourceFilesList} - This xref points to a term that is already transcluded from elsewhere`,
+            hint: 'Use [[xref]] only for terms directly defined in the external spec. For nested references, either reference the original source or define the term locally',
+            details: `This creates a chain of external references. Repository: ${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,10 +212,14 @@ 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);
+    Logger.error('Error merging xref terms into allXTrefs', {
+      context: 'Failed while merging external reference terms into the xtrefs cache',
+      hint: 'This may indicate corrupted cache files in .cache/xtrefs/. Try deleting the .cache directory and running the build again',
+      details: error.message
+    });
   }
 }
 
@@ -181,18 +247,18 @@ function extractTermsFromHtml(externalSpec, html) {
       batch.each((index, termElement) => {
         try {
           const $termElement = $(termElement);
-          
+
           // 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');
@@ -203,17 +269,23 @@ function extractTermsFromHtml(externalSpec, html) {
               }
             }
           });
-          
+
           // Skip if no valid term IDs found
           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');
 
           if (dd.length > 0) {
             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 => {
@@ -221,16 +293,21 @@ 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);
             });
           }
         } catch (termError) {
-          Logger.warn(`Error processing term in ${externalSpec}:`, termError.message);
+          Logger.warn(`Error processing term in ${externalSpec}`, {
+            context: 'Failed to extract a specific term from external spec HTML',
+            hint: 'The external spec may have malformed HTML or non-standard term definitions. Contact the spec maintainer if this persists',
+            details: termError.message
+          });
         }
       });
 
@@ -244,7 +321,11 @@ function extractTermsFromHtml(externalSpec, html) {
     return terms;
 
   } catch (error) {
-    Logger.error(`Error extracting terms from external spec '${externalSpec}':`, error.message);
+    Logger.error(`Error extracting terms from external spec '${externalSpec}'`, {
+      context: 'Failed while parsing HTML from external spec to extract term definitions',
+      hint: 'Verify that the external spec is a valid spec-up-t generated document with a proper terms-and-definitions section',
+      details: error.message
+    });
     return [];
   }
 }

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

@@ -14,7 +14,11 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
 
         allXTrefs.xtrefs = allXTrefs.xtrefs.filter(xtref => {
             if (!xtref.owner || !xtref.repo || !xtref.repoUrl) {
-                Logger.error(`Removing incomplete reference: ${xtref.externalSpec}, ${xtref.term}`);
+                Logger.error(`Removing incomplete reference: ${xtref.externalSpec}, ${xtref.term}`, {
+                    context: 'External reference is missing required repository information',
+                    hint: 'Verify external_specs configuration in specs.json includes github_repo_url for each entry',
+                    details: `Missing: ${!xtref.owner ? 'owner' : ''} ${!xtref.repo ? 'repo' : ''} ${!xtref.repoUrl ? 'repoUrl' : ''}`
+                });
                 return false;
             }
             return true;
@@ -51,7 +55,11 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
             );
 
             if (!allTermsData) {
-                Logger.error(`Could not fetch terms from repository ${repoKey} (${repoUrl})`);
+                Logger.error(`Could not fetch terms from repository ${repoKey}`, {
+                    context: `Failed to retrieve terminology from ${repoUrl}`,
+                    hint: 'Ensure the repository exists, is accessible, and has published its spec. If it\'s private, set GITHUB_PAT environment variable',
+                    details: `Repository: ${repoUrl}. Check if GitHub Pages is enabled or if the repo has a valid specs.json`
+                });
                 repoGroup.xtrefs.forEach(xtref => {
                     xtref.commitHash = 'not found';
                     xtref.content = 'This term was not found in the external repository.';
@@ -69,12 +77,54 @@ 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(`NESTED TREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec}`, {
+                            context: `Origin: ${sourceFilesList} - This term is itself a tref transcluded from another spec`,
+                            hint: 'Avoid chaining trefs (tref → tref). Either reference the original source spec directly, or define the term locally',
+                            details: `Repository: ${externalRepoUrl}. Nested trefs create complex dependency chains`
+                        });
+                    }
+
+                    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(`NESTED XREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec}`, {
+                            context: `Origin: ${sourceFilesList} - This xref points to a term that is already transcluded elsewhere`,
+                            hint: 'Use [[xref]] only for terms directly defined in the external spec. For nested refs, reference the original source',
+                            details: `Repository: ${externalRepoUrl}. This creates a chain of external references`
+                        });
+                    }
+
                     Logger.success(`Match found for term: ${xtref.term} in ${xtref.externalSpec}`);
                 } else {
                     xtref.commitHash = 'not found';
                     xtref.content = 'This term was not found in the external repository.';
                     xtref.avatarUrl = null;
-                    
+
                     // Build a readable list of source files for the error message.
                     // Two possible data structures exist:
                     // 1. xtref.sourceFile is a STRING like "primitive.md"
@@ -85,15 +135,19 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
                     // - Otherwise → extract file names from the sourceFiles array:
                     //   - .map(sf => sf.file) extracts just the filename from each object
                     //   - .join(', ') combines them into a comma-separated string
-                    const sourceFilesList = xtref.sourceFile 
-                        ? xtref.sourceFile 
+                    const sourceFilesList = xtref.sourceFile
+                        ? xtref.sourceFile
                         : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
 
                     // Prefer an explicit repo URL if provided on the xtref, otherwise
                     // build a standard GitHub URL from the owner/repo.
                     const githubUrl = xtref.repoUrl || `https://github.com/${repoKey}`;
 
-                    Logger.error(`Origin: ${sourceFilesList} 👉 No match found for term: ${xtref.term} in ${xtref.externalSpec} (${githubUrl})`);
+                    Logger.error(`No match found for term: ${xtref.term} in ${xtref.externalSpec}`, {
+                        context: `Origin: ${sourceFilesList} - Term not found in external repository`,
+                        hint: 'Check if the term exists in the external spec. Verify spelling, ensure the external spec has published, and confirm the term is in their terminology section',
+                        details: `Repository: ${githubUrl}. The term may have been renamed or removed`
+                    });
                 }
             }
 
@@ -104,10 +158,14 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
         const allXTrefsStr = JSON.stringify(allXTrefs, null, 2);
         fs.writeFileSync(outputPathJSON, allXTrefsStr, 'utf8');
         const jsPayload = `const allXTrefs = ${allXTrefsStr};`;
-    fs.writeFileSync(outputPathJS, jsPayload, 'utf8');
-    fs.writeFileSync(outputPathJSTimeStamped, jsPayload, 'utf8');
+        fs.writeFileSync(outputPathJS, jsPayload, 'utf8');
+        fs.writeFileSync(outputPathJSTimeStamped, jsPayload, 'utf8');
     } catch (error) {
-        Logger.error('An error occurred:', error);
+        Logger.error('An error occurred during xtrefs processing', {
+            context: 'Failed while processing external references and fetching terms',
+            hint: 'Check your internet connection, verify GITHUB_PAT is set if needed, and ensure specs.json external_specs configuration is correct',
+            details: error.message
+        });
     }
 }
 

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,