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

package/gulpfile.js

@@ -32,6 +32,40 @@ async function fetchSpecRefs() {
   }).catch(e => console.log(e));
 }
 
+/**
+ * Removes forbidden control characters from compiled JavaScript files
+ * to ensure W3C HTML validation compliance.
+ * 
+ * Specifically removes:
+ * - U+0001 (SOH - Start of Heading) 
+ * - U+001B (ESC - Escape, used in ANSI color codes)
+ * 
+ * These characters appear in third-party libraries (mermaid.js, dagre-d3)
+ * and cause W3C validation errors when embedded in HTML.
+ * 
+ * @param {string} filePath - Absolute path to the JavaScript file to clean
+ * @returns {Promise<void>}
+ */
+async function removeForbiddenControlCharacters(filePath) {
+  try {
+    let content = await fs.readFile(filePath, 'utf8');
+    
+    // Remove U+0001 (SOH - Start of Heading)
+    // This appears in dagre-d3 library as a null character separator
+    content = content.replace(/\x01/g, '');
+    
+    // Remove U+001B (ESC - Escape) 
+    // This appears in ANSI color codes like [35m, [31m, etc.
+    content = content.replace(/\x1b/g, '');
+    
+    await fs.writeFile(filePath, content, 'utf8');
+    console.log(`✓ Cleaned forbidden characters from ${filePath}`);
+  } catch (error) {
+    console.error(`✗ Error cleaning ${filePath}:`, error.message);
+    throw error;
+  }
+}
+
 async function compileAssets() {
   await fs.ensureDir(compileLocation);
   return new Promise(resolve => {
@@ -48,7 +82,14 @@ async function compileAssets() {
         .pipe(terser())
         .pipe(concat('body.js'))
         .pipe(gulp.dest(compileLocation))
-    ).on('finish', function () {
+    ).on('finish', async function () {
+      // Post-process compiled JavaScript files to remove forbidden control characters
+      try {
+        await removeForbiddenControlCharacters(`${compileLocation}/head.js`);
+        await removeForbiddenControlCharacters(`${compileLocation}/body.js`);
+      } catch (error) {
+        console.error('Failed to clean compiled files:', error);
+      }
       resolve();
     })
   });

package/index.js

@@ -1,7 +1,20 @@
 const { initialize } = require('./src/init');
 const Logger = require('./src/utils/logger');
+const messageCollector = require('./src/utils/message-collector');
 
 module.exports = async function (options = {}) {
+  // Start collecting messages if requested
+  const shouldCollectMessages = options.collectMessages !== false; // Collect by default
+  
+  if (shouldCollectMessages) {
+    // Only clear messages if not called from another operation (like collectExternalReferences)
+    // If skipClear is true, we're continuing from a previous operation
+    if (!options.skipClear) {
+      messageCollector.clearMessages();
+    }
+    messageCollector.startCollecting('render');
+  }
+
   try {
   const { initializeConfig } = require('./src/pipeline/configuration/prepare-spec-configuration.js');
     let toc = '';
@@ -137,8 +150,16 @@ module.exports = async function (options = {}) {
 
         // Run render and wait for it
         render(spec, assetTags, { externalReferences, references, definitions, specGroups, noticeTitles }, config, template, assets, Logger, md, externalSpecsList)
-          .then(() => {
+          .then(async () => {
             Logger.info('Render completed for:', spec.destination);
+            
+            // Save collected messages
+            if (shouldCollectMessages) {
+              messageCollector.stopCollecting();
+              const messagePath = await messageCollector.saveMessages();
+              Logger.success(`Console messages saved to: ${messagePath}`);
+            }
+            
             if (options.nowatch) {
               Logger.info('Exiting with nowatch');
               process.exit(0);
@@ -146,6 +167,15 @@ module.exports = async function (options = {}) {
           })
           .catch((e) => {
             Logger.error('Render failed:', e.message);
+            
+            // Save messages even on failure
+            if (shouldCollectMessages) {
+              messageCollector.stopCollecting();
+              messageCollector.saveMessages().catch(() => {
+                // Silent fail on save error
+              });
+            }
+            
             process.exit(1);
           });
 
@@ -159,10 +189,28 @@ module.exports = async function (options = {}) {
       });
     } catch (error) {
       Logger.error(`Error during initialization or module execution: ${error.message}`);
+      
+      // Save messages even on error
+      if (shouldCollectMessages) {
+        messageCollector.stopCollecting();
+        await messageCollector.saveMessages().catch(() => {
+          // Silent fail on save error
+        });
+      }
+      
       throw error; // Re-throw to let the caller handle the error
     }
   } catch (error) {
     Logger.error(`Error during initialization: ${error.message}`);
+    
+    // Save messages even on error
+    if (shouldCollectMessages) {
+      messageCollector.stopCollecting();
+      await messageCollector.saveMessages().catch(() => {
+        // Silent fail on save error
+      });
+    }
+    
     throw error; // Re-throw to let the caller handle the error
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.4.1",
+  "version": "1.6.0-beta.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": {
@@ -64,6 +64,7 @@
     "prismjs": "^1.24.0",
     "puppeteer": "^23.2.1",
     "readline-sync": "^1.4.10",
+    "spec-up-t-healthcheck": "^1.0.0",
     "yargs": "^17.7.2"
   },
   "overrides": {

package/src/create-docx.js

@@ -173,7 +173,7 @@ function processInlineElements(node, textRuns) {
         } else if (child.nodeType === 1) { // Element node
             const tagName = child.tagName.toLowerCase();
             const text = child.textContent.trim();
-            
+
             if (text) {
                 switch (tagName) {
                     case 'strong':
@@ -262,8 +262,11 @@ function createTitlePage(config) {
 
         // Check if HTML file exists
         if (!fs.existsSync(filePath)) {
-            Logger.error(`HTML file not found at ${filePath}`);
-            Logger.info('Please run "npm run render" first to generate the HTML file.');
+            Logger.error('HTML file not found', {
+                context: 'Cannot generate DOCX without rendered HTML',
+                hint: 'Run "npm run render" first to generate the HTML file, then run "npm run docx"',
+                details: `Expected file: ${filePath}`
+            });
             return;
         }
 
@@ -325,9 +328,13 @@ function createTitlePage(config) {
         // Write the DOCX file
         fs.writeFileSync(docxPath, buffer);
 
-    Logger.success('DOCX generated successfully! Find the DOCX file in the docs directory.');
+        Logger.success('DOCX generated successfully! Find the DOCX file in the docs directory.');
     } catch (error) {
-    Logger.error('Error generating DOCX:', error);
-    process.exit(1);
+        Logger.error('Error generating DOCX', {
+            context: 'Failed during DOCX document generation',
+            hint: 'Ensure the HTML file is valid and all dependencies are installed. Check that you have write permissions for the output directory',
+            details: error.message
+        });
+        process.exit(1);
     }
 })();

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
+        });
     }
 })();