spec-up-t 1.2.8 → 1.3.0-beta

package/src/create-pdf.js

@@ -3,14 +3,220 @@ const puppeteer = require('puppeteer');
 const path = require('path');
 const pdfLib = require('pdf-lib');
 
+// ISO compliance configuration
+const ISO_CONFIG = {
+    embedFonts: true,
+    deviceIndependentColor: true,
+    tagged: true, // For PDF/UA accessibility
+    pdfVersion: '1.7', // ISO 32000-1 compliant
+    metadata: {
+        format: 'PDF/A-2b', // Archive-friendly format
+        conformance: 'B' // Basic conformance level
+    }
+};
+
+/**
+ * Creates ISO-compliant PDF metadata
+ */
+function createISOMetadata(config) {
+    const now = new Date();
+    return {
+        title: config.specs[0].title || 'Untitled Document',
+        author: config.specs[0].author || '',
+        subject: config.specs[0].description || '',
+        keywords: config.specs[0].keywords || [],
+        creator: 'Spec-Up PDF Generator',
+        producer: 'Spec-Up with ISO Compliance',
+        creationDate: now,
+        modificationDate: now
+    };
+}
+
+/**
+ * Configures Puppeteer page for ISO compliance
+ */
+async function configurePageForISO(page) {
+    // Set device-independent color profile and font embedding
+    await page.emulateMediaType('print');
+    await page.evaluateOnNewDocument(() => {
+        // Force device-independent color rendering
+        document.documentElement.style.colorRendering = 'optimizeQuality';
+        document.documentElement.style.textRendering = 'optimizeLegibility';
+    });
+}
+
+/**
+ * Applies accessibility tags for PDF/UA compliance
+ */
+async function applyAccessibilityTags(page) {
+    await page.evaluate(() => {
+        // Add semantic structure for accessibility
+        const main = document.querySelector('main') || document.body;
+        if (main && !main.getAttribute('role')) {
+            main.setAttribute('role', 'main');
+        }
+
+        // Tag headings for proper structure
+        document.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach(heading => {
+            if (!heading.getAttribute('role')) {
+                heading.setAttribute('role', 'heading');
+                heading.setAttribute('aria-level', heading.tagName.charAt(1));
+            }
+        });
+
+        // Tag navigation elements
+        const toc = document.getElementById('toc') || document.getElementById('pdf-toc');
+        if (toc && !toc.getAttribute('role')) {
+            toc.setAttribute('role', 'navigation');
+            toc.setAttribute('aria-label', 'Table of Contents');
+        }
+
+        // Tag tables for accessibility
+        document.querySelectorAll('table').forEach(table => {
+            if (!table.getAttribute('role')) {
+                table.setAttribute('role', 'table');
+            }
+        });
+
+        // Add alt text to images if missing
+        document.querySelectorAll('img').forEach(img => {
+            if (!img.getAttribute('alt')) {
+                img.setAttribute('alt', img.getAttribute('title') || 'Image');
+            }
+        });
+    });
+}
+
+/**
+ * Creates table of contents for PDF
+ */
+async function createTOCIfNeeded(page, logo, logoLink, title, description) {
+    await page.evaluate((logo, logoLink, title, description) => {
+        const titleWrapper = document.createElement('div');
+        titleWrapper.className = 'text-center mb-5 pb-4 border-bottom';
+
+        if (logo) {
+            const logoContainer = document.createElement('a');
+            logoContainer.href = logoLink;
+            logoContainer.className = 'd-block mb-3';
+            const logoImg = document.createElement('img');
+            logoImg.src = logo;
+            logoImg.className = 'img-fluid';
+            logoContainer.appendChild(logoImg);
+            titleWrapper.appendChild(logoContainer);
+        }
+
+        if (title) {
+            const titleElement = document.createElement('h1');
+            titleElement.textContent = title;
+            titleElement.className = 'display-4 mb-2 pdf-title';
+            titleWrapper.appendChild(titleElement);
+        }
+
+        if (description) {
+            const descriptionElement = document.createElement('p');
+            descriptionElement.textContent = description;
+            descriptionElement.className = 'lead mb-0';
+            titleWrapper.appendChild(descriptionElement);
+        }
+
+        document.body.insertBefore(titleWrapper, document.body.firstChild);
+
+        // Create a Table of Contents if it doesn't exist
+        if (!document.getElementById('toc')) {
+            // Generate a TOC based on the headings in the document
+            const headings = Array.from(document.querySelectorAll('h1:not(.pdf-title), h2, h3, h4, h5, h6')).filter(h => {
+                // Only include headings with IDs that can be linked to
+                return h.id && h.id.trim() !== '';
+            });
+
+            if (headings.length > 0) {
+                // Create TOC container
+                const tocContainer = document.createElement('div');
+                tocContainer.id = 'toc';
+                tocContainer.className = 'toc-container';
+
+                // Create TOC heading
+                const tocHeading = document.createElement('h2');
+                tocHeading.textContent = 'Contents';
+                tocHeading.className = 'toc-heading';
+                tocContainer.appendChild(tocHeading);
+
+                // Create TOC list
+                const tocList = document.createElement('ul');
+                tocList.className = 'toc-list';
+                tocContainer.appendChild(tocList);
+
+                // Add all headings to the TOC
+                let currentLevel = 0;
+                let currentList = tocList;
+                let listStack = [tocList];
+
+                headings.forEach(heading => {
+                    // Get heading level (1-6 for h1-h6)
+                    const level = parseInt(heading.tagName[1]);
+
+                    // Navigate to the correct nesting level
+                    if (level > currentLevel) {
+                        // Go deeper - create a new nested list
+                        for (let i = currentLevel; i < level; i++) {
+                            if (currentList.lastChild) {
+                                const nestedList = document.createElement('ul');
+                                currentList.lastChild.appendChild(nestedList);
+                                listStack.push(nestedList);
+                                currentList = nestedList;
+                            } else {
+                                // If no items exist yet, add a dummy item
+                                const dummyItem = document.createElement('li');
+                                const nestedList = document.createElement('ul');
+                                dummyItem.appendChild(nestedList);
+                                currentList.appendChild(dummyItem);
+                                listStack.push(nestedList);
+                                currentList = nestedList;
+                            }
+                        }
+                    } else if (level < currentLevel) {
+                        // Go up - pop from the stack
+                        for (let i = currentLevel; i > level; i--) {
+                            listStack.pop();
+                        }
+                        currentList = listStack[listStack.length - 1];
+                    }
+
+                    currentLevel = level;
+
+                    // Create list item with link
+                    const listItem = document.createElement('li');
+                    const link = document.createElement('a');
+                    link.href = '#' + heading.id;
+                    link.textContent = heading.textContent;
+                    listItem.appendChild(link);
+                    currentList.appendChild(listItem);
+                });
+
+                // Insert the TOC after the title section
+                document.body.insertBefore(tocContainer, titleWrapper.nextSibling);
+
+                console.log('Generated a Table of Contents with ' + headings.length + ' entries.');
+            }
+        }
+    }, logo, logoLink, title, description);
+}
+
 (async () => {
     try {
-        // Launch a new browser instance
-        const browser = await puppeteer.launch();
+        // Launch a new browser instance with ISO-compliant settings
+        const browser = await puppeteer.launch({
+            args: ['--disable-web-security', '--allow-running-insecure-content']
+        });
         const page = await browser.newPage();
 
+        // Configure page for ISO compliance
+        await configurePageForISO(page);
+
         // Read and parse the specs.json file
         const config = fs.readJsonSync('specs.json');
+        const metadata = createISOMetadata(config);
 
         // Extract configuration details
         const outputPath = config.specs[0].output_path;
@@ -36,6 +242,9 @@ const pdfLib = require('pdf-lib');
         // Navigate to the HTML file
         await page.goto(fileUrl, { waitUntil: 'networkidle2' });
 
+        // Apply accessibility tags for PDF/UA compliance
+        await applyAccessibilityTags(page);
+
         // Clean up unnecessary elements but be careful not to remove styles we need
         await page.evaluate(() => {
             // Preserve TOC if it exists (skip removing it even if it has display:none)
@@ -131,116 +340,7 @@ const pdfLib = require('pdf-lib');
         });
 
         // Inject logo, title, and description AND handle TOC creation if needed
-        await page.evaluate((logo, logoLink, title, description) => {
-            const titleWrapper = document.createElement('div');
-            titleWrapper.className = 'text-center mb-5 pb-4 border-bottom';
-
-            if (logo) {
-                const logoContainer = document.createElement('a');
-                logoContainer.href = logoLink;
-                logoContainer.className = 'd-block mb-3';
-                const logoImg = document.createElement('img');
-                logoImg.src = logo;
-                logoImg.className = 'img-fluid';
-                logoContainer.appendChild(logoImg);
-                titleWrapper.appendChild(logoContainer);
-            }
-
-            if (title) {
-                const titleElement = document.createElement('h1');
-                titleElement.textContent = title;
-                titleElement.className = 'display-4 mb-2 pdf-title';
-                titleWrapper.appendChild(titleElement);
-            }
-
-            if (description) {
-                const descriptionElement = document.createElement('p');
-                descriptionElement.textContent = description;
-                descriptionElement.className = 'lead mb-0';
-                titleWrapper.appendChild(descriptionElement);
-            }
-
-            document.body.insertBefore(titleWrapper, document.body.firstChild);
-
-            // Create a Table of Contents if it doesn't exist
-            if (!document.getElementById('toc')) {
-                // Generate a TOC based on the headings in the document
-                const headings = Array.from(document.querySelectorAll('h1:not(.pdf-title), h2, h3, h4, h5, h6')).filter(h => {
-                    // Only include headings with IDs that can be linked to
-                    return h.id && h.id.trim() !== '';
-                });
-
-                if (headings.length > 0) {
-                    // Create TOC container
-                    const tocContainer = document.createElement('div');
-                    tocContainer.id = 'toc';
-                    tocContainer.className = 'toc-container';
-
-                    // Create TOC heading
-                    const tocHeading = document.createElement('h2');
-                    tocHeading.textContent = 'Contents';
-                    tocHeading.className = 'toc-heading';
-                    tocContainer.appendChild(tocHeading);
-
-                    // Create TOC list
-                    const tocList = document.createElement('ul');
-                    tocList.className = 'toc-list';
-                    tocContainer.appendChild(tocList);
-
-                    // Add all headings to the TOC
-                    let currentLevel = 0;
-                    let currentList = tocList;
-                    let listStack = [tocList];
-
-                    headings.forEach(heading => {
-                        // Get heading level (1-6 for h1-h6)
-                        const level = parseInt(heading.tagName[1]);
-
-                        // Navigate to the correct nesting level
-                        if (level > currentLevel) {
-                            // Go deeper - create a new nested list
-                            for (let i = currentLevel; i < level; i++) {
-                                if (currentList.lastChild) {
-                                    const nestedList = document.createElement('ul');
-                                    currentList.lastChild.appendChild(nestedList);
-                                    listStack.push(nestedList);
-                                    currentList = nestedList;
-                                } else {
-                                    // If no items exist yet, add a dummy item
-                                    const dummyItem = document.createElement('li');
-                                    const nestedList = document.createElement('ul');
-                                    dummyItem.appendChild(nestedList);
-                                    currentList.appendChild(dummyItem);
-                                    listStack.push(nestedList);
-                                    currentList = nestedList;
-                                }
-                            }
-                        } else if (level < currentLevel) {
-                            // Go up - pop from the stack
-                            for (let i = currentLevel; i > level; i--) {
-                                listStack.pop();
-                            }
-                            currentList = listStack[listStack.length - 1];
-                        }
-
-                        currentLevel = level;
-
-                        // Create list item with link
-                        const listItem = document.createElement('li');
-                        const link = document.createElement('a');
-                        link.href = '#' + heading.id;
-                        link.textContent = heading.textContent;
-                        listItem.appendChild(link);
-                        currentList.appendChild(listItem);
-                    });
-
-                    // Insert the TOC after the title section
-                    document.body.insertBefore(tocContainer, titleWrapper.nextSibling);
-
-                    console.log('Generated a Table of Contents with ' + headings.length + ' entries.');
-                }
-            }
-        }, logo, logoLink, title, description);
+        await createTOCIfNeeded(page, logo, logoLink, title, description);
 
         // Direct manipulation of definition lists and TOC to ensure proper styling in PDF
         await page.evaluate(() => {
@@ -542,16 +642,37 @@ const pdfLib = require('pdf-lib');
 
         await browser.close();
 
-        // Optimize PDF with pdf-lib
-        const pdfDoc = await pdfLib.PDFDocument.load(pdfBuffer);
-        pdfDoc.setTitle(title);
-        pdfDoc.setAuthor('');
-        pdfDoc.setSubject('');
-        pdfDoc.setKeywords([]);
-        pdfDoc.setProducer('');
-        pdfDoc.setCreator('');
-        const optimizedPdfBytes = await pdfDoc.save();
-        fs.writeFileSync('docs/index.pdf', optimizedPdfBytes);
+        console.log('✅ 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);
+            pdfDoc.setSubject(metadata.subject);
+            pdfDoc.setKeywords(metadata.keywords);
+            pdfDoc.setProducer(metadata.producer);
+            pdfDoc.setCreator(metadata.creator);
+            pdfDoc.setCreationDate(metadata.creationDate);
+            pdfDoc.setModificationDate(metadata.modificationDate);
+
+            console.log('✅ ISO metadata applied successfully.');
+
+            // Save with conservative settings to ensure compatibility
+            const optimizedPdfBytes = await pdfDoc.save({
+                useObjectStreams: false, // Required for PDF/A compliance
+                addDefaultPage: false
+            });
+            
+            fs.writeFileSync('docs/index.pdf', optimizedPdfBytes);
+            console.log('✅ PDF saved with ISO compliance features.');
+        } catch (pdfError) {
+            console.warn('⚠️  Warning: Could not apply ISO metadata, saving original PDF:', pdfError.message);
+            // Fallback: save the original PDF if post-processing fails
+            fs.writeFileSync('docs/index.pdf', pdfBuffer);
+        }
 
         console.log('✅ PDF generated successfully! Find the PDF in the docs directory.');
     } catch (error) {

package/src/escape-handler.js

@@ -0,0 +1,67 @@
+/**
+ * Escape handler for substitution tags in Spec-Up
+ * Provides mechanism to display literal [[tag]] syntax without processing
+ * 
+ * Implements a three-phase approach:
+ * 1. Pre-processing: Convert escaped sequences to temporary placeholders
+ * 2. Tag Processing: Existing substitution logic runs normally (placeholders ignored)
+ * 3. Post-processing: Restore escaped sequences as literals
+ */
+
+const ESCAPED_PLACEHOLDER = '__SPEC_UP_ESCAPED_TAG__';
+
+/**
+ * Pre-processes text to handle escaped substitution tags
+ * @param {string} text - Input text with potential escaped tags
+ * @returns {string} Text with escaped tags replaced by placeholders
+ */
+function preProcessEscapes(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+  
+  // Handle double backslash first: \\[[ → \__PLACEHOLDER__
+  let processed = text.replace(/\\\\(\[\[)/g, `\\${ESCAPED_PLACEHOLDER}`);
+  
+  // Handle single backslash: \[[ → __PLACEHOLDER__
+  processed = processed.replace(/\\(\[\[)/g, ESCAPED_PLACEHOLDER);
+  
+  return processed;
+}
+
+/**
+ * Post-processes text to restore escaped tags as literals
+ * @param {string} text - Text after substitution processing
+ * @returns {string} Text with placeholders restored to literal tags
+ */
+function postProcessEscapes(text) {
+  if (!text || typeof text !== 'string') {
+    return text;
+  }
+  
+  // Restore placeholders to literal [[
+  return text.replace(new RegExp(ESCAPED_PLACEHOLDER, 'g'), '[[');
+}
+
+/**
+ * Main processing function that wraps existing substitution logic
+ * @param {string} content - Raw markdown content
+ * @param {Function} processSubstitutions - Existing substitution processor
+ * @returns {string} Processed content with escape handling
+ */
+function processWithEscapes(content, processSubstitutions) {
+  if (!content || typeof content !== 'string') {
+    return content;
+  }
+  
+  const preProcessed = preProcessEscapes(content);
+  const substituted = processSubstitutions(preProcessed);
+  return postProcessEscapes(substituted);
+}
+
+module.exports = {
+  preProcessEscapes,
+  postProcessEscapes,
+  processWithEscapes,
+  ESCAPED_PLACEHOLDER
+};

package/src/fix-markdown-files.js

@@ -3,7 +3,24 @@ const path = require('path');
 const { shouldProcessFile } = require('./utils/file-filter');
 
 /**
- * Handles specific functionality for `[[def:` lines
+ * Checks if a term has a definition starting from the given line index
+ * @param {string[]} lines - Array of file lines
+ * @param {number} startIndex - Index to start checking from
+ * @returns {boolean} - True if definition exists, false otherwise
+ */
+function hasDefinition(lines, startIndex) {
+    for (let i = startIndex; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === '') continue; // Skip empty lines
+        if (line.startsWith('~')) return true; // Found definition
+        if (line.startsWith('[[def:') || line.startsWith('[[tref:')) return false; // Found next term
+        if (line.length > 0) return false; // Found other content
+    }
+    return false;
+}
+
+/**
+ * Handles specific functionality for `[[def:` and `[[tref:` lines
  * @param {string[]} lines - Array of file lines
  * @returns {object} - Object containing modified lines and modification status
  */
@@ -12,10 +29,19 @@ function processDefLines(lines) {
     let modified = false;
 
     for (let i = 0; i < result.length; i++) {
-        if (result[i].startsWith('[[def:')) {
-            // Ensure a blank line immediately follows `[[def:` lines
-            if (i + 1 < result.length && result[i + 1].trim() !== '') {
-                result.splice(i + 1, 0, ''); // Insert blank line
+        if (result[i].startsWith('[[def:') || result[i].startsWith('[[tref:')) {
+            let insertIndex = i + 1;
+            
+            // Ensure a blank line immediately follows `[[def:` and `[[tref:` lines
+            if (insertIndex < result.length && result[insertIndex].trim() !== '') {
+                result.splice(insertIndex, 0, ''); // Insert blank line
+                insertIndex++;
+                modified = true;
+            }
+            
+            // Check if term has a definition
+            if (!hasDefinition(result, insertIndex)) {
+                result.splice(insertIndex, 0, '', '~ No local definition found.', '');
                 modified = true;
             }
         }
@@ -51,31 +77,6 @@ function normalizeParagraphSpacing(lines) {
     return { lines: newLines, modified };
 }
 
-/**
- * Prepends `~ ` to appropriate lines
- * @param {string[]} lines - Array of file lines
- * @returns {object} - Object containing modified lines and modification status
- */
-function prependTildeToLines(lines) {
-    const result = [...lines];
-    let modified = false;
-
-    for (let i = 0; i < result.length; i++) {
-        if (
-            !result[i].startsWith('[[def:') &&
-            !result[i].startsWith('[[tref:') &&
-            result[i].trim() !== '' &&
-            !result[i].startsWith('~ ') &&
-            !result[i].trim().startsWith('<!--')
-        ) {
-            result[i] = `~ ${result[i]}`;
-            modified = true;
-        }
-    }
-
-    return { lines: result, modified };
-}
-
 /**
  * Ensures there is exactly one blank line at the end of the file
  * @param {string[]} lines - Array of file lines
@@ -116,10 +117,6 @@ function processMarkdownFile(filePath, fileName) {
         lines = spacingResult.lines;
         modified = modified || spacingResult.modified;
 
-        const tildeResult = prependTildeToLines(lines);
-        lines = tildeResult.lines;
-        modified = modified || tildeResult.modified;
-
         const newlineResult = ensureTrailingNewline(lines);
         lines = newlineResult.lines;
         modified = modified || newlineResult.modified;