spec-up-t 1.5.0 → 1.6.0-beta.2

package/src/create-pdf.js

@@ -198,7 +198,7 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
                 // Insert the TOC after the title section
                 document.body.insertBefore(tocContainer, titleWrapper.nextSibling);
 
-                        console.log('Generated a Table of Contents with ' + headings.length + ' entries.');
+                console.log('Generated a Table of Contents with ' + headings.length + ' entries.');
             }
         }
     }, logo, logoLink, title, description);
@@ -254,7 +254,7 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
 
             // If TOC doesn't exist, we'll need to create one
             if (!document.getElementById('toc')) {
-                        console.log('No TOC found in the document. Will create one.');
+                console.log('No TOC found in the document. Will create one.');
             }
         });
 
@@ -508,7 +508,7 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
             }
         });
 
-    Logger.process('Generating PDF with proper TOC page numbers...');
+        Logger.process('Generating PDF with proper TOC page numbers...');
 
         // First, generate a draft PDF to calculate the page positions of each heading
         const draftPdfBuffer = await page.pdf({
@@ -530,28 +530,28 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
             // Find the PDF TOC 
             const pdfToc = document.getElementById('pdf-toc');
             if (!pdfToc) return;
-            
+
             const tocEntries = pdfToc.querySelectorAll('.toc-page-number');
             const originalToc = document.getElementById('toc');
-            
+
             if (originalToc) {
                 // Get all links from the original TOC that have tooltip data
                 const originalLinks = originalToc.querySelectorAll('a[title], a[data-bs-title]');
-                
+
                 // Create a mapping from heading IDs to page numbers based on tooltips
                 const idToPageMap = {};
-                
+
                 originalLinks.forEach(link => {
                     // Extract the heading ID from href
                     const href = link.getAttribute('href');
                     if (!href || !href.startsWith('#')) return;
-                    
+
                     const headingId = href.substring(1);
-                    
+
                     // Extract page number from tooltip text (e.g., "Go to page 5")
                     const tooltipText = link.getAttribute('title') || link.getAttribute('data-bs-title');
                     if (!tooltipText) return;
-                    
+
                     const pageNumberMatch = tooltipText.match(/Go to page (\d+)/i);
                     if (pageNumberMatch && pageNumberMatch[1]) {
                         const pageNumber = parseInt(pageNumberMatch[1], 10);
@@ -560,7 +560,7 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
                         }
                     }
                 });
-                
+
                 // Now update the TOC page numbers using the extracted values
                 tocEntries.forEach(entry => {
                     const targetId = entry.getAttribute('data-for-id');
@@ -578,10 +578,10 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
             } else {
                 // Fallback to old estimation method if original TOC is not available
                 console.log('Original TOC not found, using page number estimation method');
-                
+
                 // Find all headings with IDs (potential TOC targets)
                 const headingsWithIds = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6')).filter(h => h.id);
-                
+
                 // Use real offsets for more accurate page numbers
                 const idToPosition = {};
 
@@ -643,12 +643,12 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
 
         await browser.close();
 
-    Logger.success('PDF generated by Puppeteer. Processing with pdf-lib for ISO compliance...');
+        Logger.success('PDF generated by Puppeteer. Processing with pdf-lib for ISO compliance...');
 
         // Optimize PDF with pdf-lib for ISO compliance
         try {
             const pdfDoc = await pdfLib.PDFDocument.load(pdfBuffer);
-            
+
             // Set ISO-compliant metadata (this is safer than XMP embedding)
             pdfDoc.setTitle(metadata.title);
             pdfDoc.setAuthor(metadata.author);
@@ -666,7 +666,7 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
                 useObjectStreams: false, // Required for PDF/A compliance
                 addDefaultPage: false
             });
-            
+
             fs.writeFileSync('docs/index.pdf', optimizedPdfBytes);
             Logger.success('PDF saved with ISO compliance features.');
         } catch (pdfError) {
@@ -675,8 +675,12 @@ async function createTOCIfNeeded(page, logo, logoLink, title, description) {
             fs.writeFileSync('docs/index.pdf', pdfBuffer);
         }
 
-    Logger.success('PDF generated successfully! Find the PDF in the docs directory.');
+        Logger.success('PDF generated successfully! Find the PDF in the docs directory.');
     } catch (error) {
-        Logger.error('Error generating PDF: %o', error);
+        Logger.error('Error generating PDF', {
+            context: 'Failed during PDF document generation',
+            hint: 'Ensure the HTML file exists (run "npm run render" first), Puppeteer is installed, and you have write permissions',
+            details: error.message || error
+        });
     }
 })();

package/src/init.js

@@ -8,14 +8,14 @@ async function initialize() {
     try {
         // Ensure the .cache directory exists
         await fs.ensureDir(outputDir);
-        
+
         // Check if the init script has already run
         if (await fs.pathExists(initFlagPath)) {
             return;
         }
 
         // Place the init script here
-        
+
         // End of the init script
 
         // Create the init flag file
@@ -23,7 +23,11 @@ async function initialize() {
 
         Logger.success('Initialization complete.');
     } catch (error) {
-        Logger.error(`Initialization failed: ${error.message}`);
+        Logger.error('Initialization failed', {
+            context: 'Failed to set up spec-up-t boilerplate files',
+            hint: 'Ensure you have write permissions in the current directory. Try running with appropriate permissions or in a different directory',
+            details: error.message
+        });
     }
 }
 

package/src/install-from-boilerplate/boilerplate/spec/terms-and-definitions-intro.md

@@ -1 +1 @@
-[//]: # (This file, named “terms-and-definitions-intro.md” is mandatory and should not be deleted.)
+[//]: # (This file, named “terms-and-definitions-intro.md” is mandatory and should not be deleted. However, you can safely delete this comment and replace it with text of your choice.)

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

@@ -13,7 +13,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 { whitespace, htmlComments, contentCleaning, externalReferences, utils } = require('../utils/regex-patterns');
 const Logger = require('../utils/logger.js');
 
 /**
@@ -33,7 +33,7 @@ function extractCurrentFile(token, globalState) {
  * @param {Object} config - Configuration object containing specs and settings
  * @param {Object} globalState - Global state object containing definitions, references, etc.
  * @param {Object} token - The markdown-it token being processed
- * @param {string} type - The type of construct (def, ref, xref, tref)
+ * @param {string} type - The type of construct (def, ref, iref, xref, tref)
  * @param {string} primary - The primary content/term
  * @returns {string} The rendered HTML for the construct
  */
@@ -45,6 +45,8 @@ function parseTemplateTag(config, globalState, token, type, primary) {
   switch (type) {
     case 'def':
       return parseDef(globalState, token, primary, currentFile);
+    case 'iref':
+      return parseIref(globalState, primary);
     case 'xref':
       return parseXref(config, token);
     case 'tref':
@@ -109,7 +111,10 @@ function parseDef(globalState, token, primary, currentFile) {
   // IDs stay intact - we create an ID for the original term and each alias
   return token.info.args.reduce((acc, syn) => {
     // Generate a unique term ID by normalizing the synonym: replace whitespace with hyphens and convert to lowercase. The ID is used for fragment identifier (hash) in the URL, which in turn can be used for an anchor in a web page.
-    const termId = `term:${syn.replace(whitespace.oneOrMore, '-').toLowerCase()}`;
+    // Apply sanitization to remove special characters that would break CSS selectors
+    const normalizedSyn = syn.replace(whitespace.oneOrMore, '-').toLowerCase();
+    const sanitizedSyn = utils.sanitizeTermId(normalizedSyn);
+    const termId = `term:${sanitizedSyn}`;
     return `<span id="${termId}">${acc}</span>`;
   }, displayText);
 }
@@ -130,6 +135,25 @@ function parseRef(globalState, primary) {
   return `<a class="term-reference" href="#term:${termId}">${primary}</a>`;
 }
 
+/**
+ * Processes [[iref: term]] constructs
+ * Creates a placeholder that will be replaced client-side with a copy of the term definition
+ * This allows inline copying of existing term definitions from the terms-and-definitions-list
+ * @param {Object} globalState - Global state to track inline references
+ * @param {string} primary - The term to inline copy
+ * @returns {string} HTML placeholder element that will be replaced by client-side script
+ */
+function parseIref(globalState, primary) {
+  // Track this inline reference for validation purposes
+  globalState.references.push(primary);
+
+  // Create a placeholder span with data attribute containing the term to copy
+  // The client-side script (insert-irefs.js) will find this and replace it with
+  // a copy of the actual <dt> and <dd> elements from the terms-and-definitions-list
+  const termId = primary.replace(whitespace.oneOrMore, '-').toLowerCase();
+  return `<span class="iref-placeholder" data-iref-term="${termId}" data-iref-original="${primary}"></span>`;
+}
+
 /**
  * Processes [[xref: spec, term, alias, ...]] constructs
  * Creates links to external specification terms with tooltips
@@ -217,7 +241,10 @@ function parseTref(token) {
 
   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()}`;
+    // Apply sanitization to remove special characters that would break CSS selectors
+    const normalizedSyn = syn.replace(whitespace.oneOrMore, '-').toLowerCase();
+    const sanitizedSyn = utils.sanitizeTermId(normalizedSyn);
+    const termId = `term:${sanitizedSyn}`;
     // 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}"` : '';
@@ -298,6 +325,7 @@ module.exports = {
   createTemplateTagParser,
   // Export individual functions for testing purposes
   parseDef,
+  parseIref,
   parseXref,
   parseTref,
   parseRef,

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

@@ -46,7 +46,11 @@ function normalizeSpecConfiguration(config, { noSpecsMessage }) {
     const specs = Array.isArray(config?.specs) ? config.specs : [];
 
     if (specs.length === 0) {
-        Logger.error(noSpecsMessage);
+        Logger.error(noSpecsMessage, {
+            context: 'specs.json is missing or has no specs array',
+            hint: 'Create a valid specs.json file in your project root. Run "npm run init" or copy from: https://github.com/trustoverip/spec-up-t-starter-pack',
+            details: 'The specs array is required to configure your specification'
+        });
         return null;
     }
 
@@ -65,7 +69,11 @@ function normalizeSpecConfiguration(config, { noSpecsMessage }) {
  */
 function extendXTrefs(config, xtrefs) {
     if (config.specs[0].external_specs_repos) {
-        Logger.warn('Your specs.json file uses an outdated structure. Update it using: https://github.com/trustoverip/spec-up-t/blob/master/src/install-from-boilerplate/boilerplate/specs.json');
+        Logger.warn('Your specs.json file uses an outdated structure', {
+            context: 'The "external_specs_repos" field is deprecated',
+            hint: 'Update to the new structure using "external_specs" instead. See: https://github.com/trustoverip/spec-up-t/blob/master/src/install-from-boilerplate/boilerplate/specs.json',
+            details: 'External references may not work correctly with the old structure'
+        });
         return;
     }
 
@@ -118,7 +126,11 @@ function extendXTrefs(config, xtrefs) {
         try {
             xtref.branch = getCurrentBranch();
         } catch (error) {
-            Logger.warn(`Could not get current branch for xtref ${xtref.externalSpec}:${xtref.term}: ${error.message}`);
+            Logger.warn(`Could not get current branch for xtref ${xtref.externalSpec}:${xtref.term}`, {
+                context: 'Git branch detection failed for external reference',
+                hint: 'Ensure you\'re in a git repository, or specify github_repo_branch in specs.json external_specs configuration',
+                details: `${error.message}. Using default: main`
+            });
             xtref.branch = 'main';
         }
     });
@@ -153,7 +165,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
                 }
 
                 const userInput = readlineSync.question(
-`❌ This external reference is not a valid URL:
+                    `❌ This external reference is not a valid URL:
 
    Repository: ${repo.url},
    
@@ -195,14 +207,22 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
         const termsDir = spec?.spec_terms_directory;
 
         if (!specDir || !termsDir) {
-            Logger.warn(`Spec entry is missing spec_directory or spec_terms_directory: ${JSON.stringify(spec)}`);
+            Logger.warn(`Spec entry is missing spec_directory or spec_terms_directory`, {
+                context: 'Invalid specs.json configuration',
+                hint: 'Ensure each spec in specs.json has both "spec_directory" and "spec_terms_directory" fields',
+                details: `Incomplete spec entry: ${JSON.stringify(spec)}`
+            });
             return directories;
         }
 
         const resolvedDir = path.join(specDir, termsDir);
 
         if (!fs.existsSync(resolvedDir)) {
-            Logger.warn(`Spec terms directory does not exist: ${resolvedDir}`);
+            Logger.warn(`Spec terms directory does not exist: ${resolvedDir}`, {
+                context: 'Directory specified in specs.json not found',
+                hint: 'Create the directory or update the path in specs.json. Typically this should be "spec/term-definitions" or similar',
+                details: `Expected path: ${resolvedDir}`
+            });
             return directories;
         }
 
@@ -211,7 +231,11 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
     }, []);
 
     if (specTermsDirectories.length === 0) {
-        Logger.warn('No spec terms directories found. Skipping external reference collection.');
+        Logger.warn('No spec terms directories found. Skipping external reference collection', {
+            context: 'Cannot collect external references without valid terminology directories',
+            hint: 'Check specs.json configuration. Ensure spec_directory and spec_terms_directory point to existing directories',
+            details: 'External trefs and xrefs will not be processed'
+        });
         return;
     }
 
@@ -249,7 +273,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
 function collectExternalReferences(options = {}) {
     // Start collecting messages if requested
     const shouldCollectMessages = options.collectMessages !== false; // Collect by default
-    
+
     if (shouldCollectMessages) {
         messageCollector.clearMessages();
         messageCollector.startCollecting('collectExternalReferences');
@@ -273,8 +297,11 @@ function collectExternalReferences(options = {}) {
     const GITHUB_API_TOKEN = options.pat || process.env.GITHUB_API_TOKEN;
 
     if (!GITHUB_API_TOKEN) {
-        Logger.warn('No GitHub Personal Access Token (PAT) found. Running without authentication (may hit rate limits).');
-        Logger.info('For better performance, set up a PAT: https://trustoverip.github.io/spec-up-t-website/docs/getting-started/github-token\n');
+        Logger.warn('No GitHub Personal Access Token (PAT) found. Running without authentication', {
+            context: 'GitHub API requests will use unauthenticated access',
+            hint: 'Set GITHUB_PAT environment variable to increase rate limit from 60 to 5000 requests/hour. See: https://trustoverip.github.io/spec-up-t-website/docs/getting-started/github-token',
+            details: 'You may hit rate limits when fetching many external references'
+        });
     }
 
     // Communicate that the expected external_specs array is missing entirely.
@@ -282,7 +309,7 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'No external_specs array found on the first spec entry in specs.json. External reference collection is skipped.'
         );
-        
+
         if (shouldCollectMessages) {
             messageCollector.stopCollecting();
             messageCollector.saveMessages().then(path => {
@@ -300,7 +327,7 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'The external_specs array in specs.json is empty. Add external repositories to collect external references.'
         );
-        
+
         if (shouldCollectMessages) {
             messageCollector.stopCollecting();
             messageCollector.saveMessages().then(path => {
@@ -333,14 +360,14 @@ function collectExternalReferences(options = {}) {
             })
             .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 {

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

@@ -17,7 +17,11 @@ function validateReferences(references, definitions, render) {
     }
   );
   if (unresolvedRefs.length > 0) {
-    Logger.warn(`Unresolved References: ${unresolvedRefs.join(',')}`);
+    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.warn(`Dangling Definitions: ${danglingDefs.join(',')}`);
+    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 [];
   }
 }
@@ -132,7 +148,7 @@ 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] = {
           ...existingXtref,
@@ -151,26 +167,34 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
 
         if (isExternalTref && isTref) {
           // Build a readable list of source files for the error message
-          const sourceFilesList = existingXtref.sourceFile 
-            ? existingXtref.sourceFile 
+          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.`);
+
+          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 
+          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})`);
+
+          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++;
@@ -191,7 +215,11 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
     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
+    });
   }
 }
 
@@ -219,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');
@@ -241,7 +269,7 @@ function extractTermsFromHtml(externalSpec, html) {
               }
             }
           });
-          
+
           // Skip if no valid term IDs found
           if (termIds.length === 0) {
             return;
@@ -252,12 +280,12 @@ function extractTermsFromHtml(externalSpec, html) {
           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 => {
@@ -275,7 +303,11 @@ function extractTermsFromHtml(externalSpec, html) {
             });
           }
         } 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
+          });
         }
       });
 
@@ -289,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 [];
   }
 }