spec-up-t 1.6.3-beta.1 → 1.6.4

package/assets/js/validate-external-refs.js

@@ -53,6 +53,13 @@ const VALIDATOR_CONFIG = {
  */
 const fetchCache = new Map();
 
+/**
+ * Collector for validation results to populate the changes report
+ * Each entry contains details about a changed or missing reference
+ * @type {Array<Object>}
+ */
+const validationResults = [];
+
 /**
  * Normalizes HTML content for comparison by extracting text and normalizing whitespace
  * This helps compare definitions that might have minor formatting differences
@@ -391,6 +398,23 @@ function truncateText(text, maxLength) {
     return text.substring(0, maxLength) + '...';
 }
 
+/**
+ * Records a validation result for the changes report
+ * 
+ * @param {Object} result - The validation result to record
+ * @param {string} result.type - 'changed', 'missing', or 'error'
+ * @param {string} result.refType - 'xref' or 'tref'
+ * @param {string} result.term - The term name
+ * @param {string} result.externalSpec - The external specification name
+ * @param {string} [result.similarity] - Similarity percentage (for changed)
+ * @param {string} [result.oldContent] - Old cached content
+ * @param {string} [result.newContent] - New live content
+ * @param {HTMLElement} result.element - The DOM element
+ */
+function recordValidationResult(result) {
+    validationResults.push(result);
+}
+
 /**
  * Validates a single xref element against live data
  * 
@@ -409,6 +433,13 @@ function validateXref(element, liveData, cachedXtref) {
     if (liveTerms === null) {
         const indicator = createIndicator('error');
         insertIndicatorAfterElement(element, indicator);
+        recordValidationResult({
+            type: 'error',
+            refType: 'xref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            element: element
+        });
         return;
     }
     
@@ -423,6 +454,13 @@ function validateXref(element, liveData, cachedXtref) {
     if (!liveTerm) {
         const indicator = createIndicator('missing');
         insertIndicatorAfterElement(element, indicator);
+        recordValidationResult({
+            type: 'missing',
+            refType: 'xref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            element: element
+        });
         return;
     }
     
@@ -453,12 +491,28 @@ function validateXref(element, liveData, cachedXtref) {
     
     // Only show changed indicator if similarity is below threshold (significant change)
     if (similarity < VALIDATOR_CONFIG.similarityThreshold) {
+        const oldContent = cachedXtref.content ? extractTextFromHtml(cachedXtref.content) : 'No cached content';
+        const newContent = liveTerm.content || 'No live content';
+        const similarityPercent = (similarity * 100).toFixed(1) + '%';
+        
         const indicator = createIndicator('changed', {
-            oldContent: cachedXtref.content ? extractTextFromHtml(cachedXtref.content) : 'No cached content',
-            newContent: liveTerm.content || 'No live content',
-            similarity: (similarity * 100).toFixed(1) + '%'
+            oldContent: oldContent,
+            newContent: newContent,
+            similarity: similarityPercent
         });
         insertIndicatorAfterElement(element, indicator);
+        
+        // Record for the changes report
+        recordValidationResult({
+            type: 'changed',
+            refType: 'xref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            similarity: similarityPercent,
+            oldContent: oldContent,
+            newContent: newContent,
+            element: element
+        });
         return;
     }
     
@@ -487,6 +541,13 @@ function validateTref(element, liveData, cachedXtref) {
     if (liveTerms === null) {
         const indicator = createIndicator('error');
         insertIndicatorIntoTref(element, indicator);
+        recordValidationResult({
+            type: 'error',
+            refType: 'tref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            element: element
+        });
         return;
     }
     
@@ -501,6 +562,13 @@ function validateTref(element, liveData, cachedXtref) {
     if (!liveTerm) {
         const indicator = createIndicator('missing');
         insertIndicatorIntoTref(element, indicator);
+        recordValidationResult({
+            type: 'missing',
+            refType: 'tref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            element: element
+        });
         return;
     }
     
@@ -531,12 +599,28 @@ function validateTref(element, liveData, cachedXtref) {
     
     // Only show changed indicator if similarity is below threshold (significant change)
     if (similarity < VALIDATOR_CONFIG.similarityThreshold) {
+        const oldContent = cachedXtref.content ? extractTextFromHtml(cachedXtref.content) : 'No cached content';
+        const newContent = liveTerm.content || 'No live content';
+        const similarityPercent = (similarity * 100).toFixed(1) + '%';
+        
         const indicator = createIndicator('changed', {
-            oldContent: cachedXtref.content ? extractTextFromHtml(cachedXtref.content) : 'No cached content',
-            newContent: liveTerm.content || 'No live content',
-            similarity: (similarity * 100).toFixed(1) + '%'
+            oldContent: oldContent,
+            newContent: newContent,
+            similarity: similarityPercent
         });
         insertIndicatorIntoTref(element, indicator);
+        
+        // Record for the changes report
+        recordValidationResult({
+            type: 'changed',
+            refType: 'tref',
+            term: cachedXtref.term,
+            externalSpec: cachedXtref.externalSpec,
+            similarity: similarityPercent,
+            oldContent: oldContent,
+            newContent: newContent,
+            element: element
+        });
         return;
     }
     
@@ -571,6 +655,8 @@ function insertIndicatorAfterElement(element, indicator) {
         return; // Already has an indicator
     }
     element.insertAdjacentElement('afterend', indicator);
+    // Attach click handler if this indicator has details
+    attachClickHandler(indicator);
 }
 
 /**
@@ -592,8 +678,48 @@ function insertIndicatorIntoTref(dtElement, indicator) {
     }
     
     termSpan.appendChild(indicator);
+    // Attach click handler if this indicator has details
+    attachClickHandler(indicator);
+}
+
+/**
+ * Attaches click handlers to validation indicators for toggling details visibility
+ * Closes details when clicking outside the indicator
+ * 
+ * @param {HTMLElement} indicator - The indicator element with details
+ */
+function attachClickHandler(indicator) {
+    if (!indicator.classList.contains('has-details')) {
+        return; // Only attach handlers to indicators with details
+    }
+    
+    /**
+     * Toggle the active state when clicking the indicator
+     */
+    indicator.addEventListener('click', (event) => {
+        event.stopPropagation();
+        // Close all other open indicators
+        const allActive = document.querySelectorAll('.external-ref-validation-indicator.active');
+        for (const el of allActive) {
+            if (el !== indicator) {
+                el.classList.remove('active');
+            }
+        }
+        // Toggle this indicator
+        indicator.classList.toggle('active');
+    });
 }
 
+/**
+ * Close all open indicator details when clicking anywhere on the document
+ */
+document.addEventListener('click', () => {
+    const allActive = document.querySelectorAll('.external-ref-validation-indicator.active');
+    for (const indicator of allActive) {
+        indicator.classList.remove('active');
+    }
+});
+
 /**
  * Collects all unique external specifications from the page
  * by examining xref and tref elements
@@ -724,16 +850,239 @@ async function validateExternalRefs() {
     
     console.log('[External Ref Validator] Validation complete');
     
+    // Populate the changes report in the slide-in menu
+    populateChangesReport();
+    
     // Dispatch event to signal validation is complete
     document.dispatchEvent(new CustomEvent('external-refs-validated', {
         detail: {
             specsValidated: specs.size,
             xrefsValidated: xrefElements.length,
-            trefsValidated: trefElements.length
+            trefsValidated: trefElements.length,
+            issuesFound: validationResults.length
         }
     }));
 }
 
+/**
+ * Populates the external reference changes report in the slide-in settings menu
+ * Creates an accessible table showing all changed, missing, or error references
+ */
+function populateChangesReport() {
+    const section = document.getElementById('external-ref-changes-section');
+    const container = document.getElementById('external-ref-changes-container');
+    const badge = document.getElementById('external-ref-changes-badge');
+    const status = document.getElementById('external-ref-validation-status');
+    const divider = document.getElementById('external-ref-changes-divider');
+    
+    // If elements don't exist, skip (template may not include them)
+    if (!section || !container) {
+        console.log('[External Ref Validator] Changes report section not found in template');
+        return;
+    }
+    
+    // Show the section
+    section.style.display = 'block';
+    if (divider) {
+        divider.style.display = 'block';
+    }
+    
+    // Update status
+    if (status) {
+        if (validationResults.length === 0) {
+            status.innerHTML = '<i class="bi bi-check-circle-fill text-success me-1"></i>All external references are up to date';
+        } else {
+            status.innerHTML = `<i class="bi bi-exclamation-triangle-fill text-warning me-1"></i>${validationResults.length} issue(s) found`;
+        }
+    }
+    
+    // Update badge
+    if (badge) {
+        badge.textContent = validationResults.length;
+        if (validationResults.length === 0) {
+            badge.classList.remove('bg-warning', 'bg-danger');
+            badge.classList.add('bg-success');
+        } else {
+            const hasErrors = validationResults.some(r => r.type === 'missing' || r.type === 'error');
+            badge.classList.remove('bg-success', hasErrors ? 'bg-warning' : 'bg-danger');
+            badge.classList.add(hasErrors ? 'bg-danger' : 'bg-warning');
+        }
+    }
+    
+    // If no issues, show a simple message
+    if (validationResults.length === 0) {
+        container.innerHTML = '<p class="small text-success mb-0"><i class="bi bi-check-circle me-1"></i>No changes detected</p>';
+        return;
+    }
+    
+    // Build an accessible table with the results
+    const table = buildChangesTable(validationResults);
+    container.innerHTML = '';
+    container.appendChild(table);
+}
+
+/**
+ * Builds an accessible HTML table from the validation results
+ * 
+ * @param {Array<Object>} results - The validation results to display
+ * @returns {HTMLElement} - The table element
+ */
+function buildChangesTable(results) {
+    const table = document.createElement('table');
+    table.classList.add('table', 'table-sm', 'table-hover', 'external-ref-changes-table');
+    table.setAttribute('role', 'table');
+    table.setAttribute('aria-label', 'External reference changes report');
+    
+    // Table header
+    const thead = document.createElement('thead');
+    thead.innerHTML = `
+        <tr>
+            <th scope="col" class="col-status">Status</th>
+            <th scope="col" class="col-term">Term</th>
+            <th scope="col" class="col-spec">Source</th>
+            <th scope="col" class="col-similarity">Match</th>
+            <th scope="col" class="col-action">Action</th>
+        </tr>
+    `;
+    table.appendChild(thead);
+    
+    // Table body
+    const tbody = document.createElement('tbody');
+    
+    results.forEach((result, index) => {
+        const row = createResultRow(result, index);
+        tbody.appendChild(row);
+    });
+    
+    table.appendChild(tbody);
+    return table;
+}
+
+/**
+ * Creates a table row for a single validation result
+ * 
+ * @param {Object} result - The validation result
+ * @param {number} index - Row index for accessibility
+ * @returns {HTMLTableRowElement} - The table row element
+ */
+function createResultRow(result, index) {
+    const row = document.createElement('tr');
+    row.classList.add(`result-${result.type}`);
+    row.setAttribute('data-result-index', index);
+    
+    // Status cell with icon
+    const statusCell = document.createElement('td');
+    statusCell.classList.add('col-status');
+    statusCell.innerHTML = getStatusIcon(result.type);
+    statusCell.setAttribute('title', getStatusTitle(result.type));
+    row.appendChild(statusCell);
+    
+    // Term cell
+    const termCell = document.createElement('td');
+    termCell.classList.add('col-term');
+    termCell.innerHTML = `<span class="term-name">${escapeHtml(result.term)}</span>`;
+    row.appendChild(termCell);
+    
+    // Source/spec cell
+    const specCell = document.createElement('td');
+    specCell.classList.add('col-spec');
+    specCell.innerHTML = `<span class="spec-badge">${escapeHtml(result.externalSpec)}</span>`;
+    row.appendChild(specCell);
+    
+    // Similarity cell (for changed items)
+    const similarityCell = document.createElement('td');
+    similarityCell.classList.add('col-similarity');
+    if (result.type === 'changed' && result.similarity) {
+        similarityCell.innerHTML = `<span class="similarity-value">${result.similarity}</span>`;
+    } else {
+        similarityCell.innerHTML = '<span class="similarity-na">—</span>';
+    }
+    row.appendChild(similarityCell);
+    
+    // Action cell with button to scroll to the element
+    const actionCell = document.createElement('td');
+    actionCell.classList.add('col-action');
+    const goButton = document.createElement('button');
+    goButton.classList.add('btn', 'btn-sm', 'btn-outline-primary', 'go-to-ref-btn');
+    goButton.innerHTML = '<i class="bi bi-arrow-right-circle"></i>';
+    goButton.setAttribute('title', 'Go to reference');
+    goButton.setAttribute('aria-label', `Go to ${result.term} reference`);
+    goButton.addEventListener('click', () => scrollToElement(result.element));
+    actionCell.appendChild(goButton);
+    row.appendChild(actionCell);
+    
+    return row;
+}
+
+/**
+ * Returns the appropriate status icon HTML for a result type
+ * 
+ * @param {string} type - The result type: 'changed', 'missing', or 'error'
+ * @returns {string} - HTML string for the icon
+ */
+function getStatusIcon(type) {
+    switch (type) {
+        case 'changed':
+            return '<span class="status-icon status-changed" aria-label="Changed">🔄</span>';
+        case 'missing':
+            return '<span class="status-icon status-missing" aria-label="Missing">⚠️</span>';
+        case 'error':
+            return '<span class="status-icon status-error" aria-label="Error">❌</span>';
+        default:
+            return '<span class="status-icon" aria-label="Unknown">❓</span>';
+    }
+}
+
+/**
+ * Returns the status title for a result type
+ * 
+ * @param {string} type - The result type
+ * @returns {string} - Human-readable status title
+ */
+function getStatusTitle(type) {
+    switch (type) {
+        case 'changed':
+            return 'Definition has changed in the external specification';
+        case 'missing':
+            return 'Term no longer exists in the external specification';
+        case 'error':
+            return 'Could not fetch external specification for validation';
+        default:
+            return 'Unknown status';
+    }
+}
+
+/**
+ * Scrolls to the element in the document and highlights it temporarily
+ * Also closes the offcanvas menu
+ * 
+ * @param {HTMLElement} element - The element to scroll to
+ */
+function scrollToElement(element) {
+    if (!element) return;
+    
+    // Close the offcanvas settings panel
+    const offcanvas = document.getElementById('offcanvasSettings');
+    if (offcanvas) {
+        const bsOffcanvas = bootstrap.Offcanvas.getInstance(offcanvas);
+        if (bsOffcanvas) {
+            bsOffcanvas.hide();
+        }
+    }
+    
+    // Small delay to let the offcanvas close
+    setTimeout(() => {
+        // Scroll to the element
+        element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        
+        // Add a temporary highlight effect
+        element.classList.add('highlight-ref');
+        setTimeout(() => {
+            element.classList.remove('highlight-ref');
+        }, 2000);
+    }, 300);
+}
+
 /**
  * Initialize the validator when DOM and trefs are ready
  * We wait for the 'trefs-inserted' event to ensure all content is in place

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.3-beta.1",
+  "version": "1.6.4",
   "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": {
@@ -29,12 +29,12 @@
     "chalk": "^4.1.2",
     "cheerio": "^1.1.2",
     "dedent": "^1.5.3",
-    "diff": "^7.0.0",
+    "diff": "^8.0.3",
     "docx": "^8.5.0",
     "dotenv": "^16.4.7",
     "find-pkg-dir": "^2.0.0",
     "fs-extra": "^11.3.0",
-    "gulp": "4.0.2",
+    "gulp": "^5.0.1",
     "gulp-clean-css": "4.3.0",
     "gulp-concat": "2.6.1",
     "gulp-terser": "^2.1.0",

package/src/add-remove-xref-source.js

@@ -41,7 +41,6 @@ function askMode() {
 const questions = [
     'Enter URL of the repository: ',
     'Enter URL of the GitHub page: ',
-    'Enter the directory where the terms can be found: ',
     'Enter short unique name: ',
 ];
 
@@ -64,9 +63,6 @@ function askQuestion(index) {
                 inputs.gh_page = answer;
                 break;
             case 2:
-                inputs.terms_dir = answer;
-                break;
-            case 3:
                 inputs.external_spec = answer;
                 break;
         }
@@ -92,7 +88,6 @@ function showReferences() {
         Logger.highlight(`Short name: ${spec.external_spec}`);
         Logger.info(`GitHub Page: ${spec.gh_page}`);
         Logger.info(`URL: ${spec.url}`);
-        Logger.info(`Terms Directory: ${spec.terms_dir}`);
         Logger.separator();
     });
     rl.close();

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

@@ -155,6 +155,104 @@ That's all about these references.`,
     });
 });
 
+describe('Cleanup of deleted files from sourceFiles array', () => {
+
+    // Test: Are deleted files removed from sourceFiles arrays?
+    it('should remove deleted files from sourceFiles array when files no longer exist', () => {
+        // Setup: Create an allXTrefs structure with multiple source files
+        const allXTrefs = { 
+            xtrefs: [
+                {
+                    externalSpec: 'ExtRef1',
+                    term: 'greenhouse',
+                    trefAliases: [],
+                    xrefAliases: [],
+                    sourceFiles: [
+                        { file: 'composability.md', type: 'tref' },
+                        { file: 'greenhouse.md', type: 'tref' },
+                        { file: 'soil.md', type: 'xref' }
+                    ]
+                },
+                {
+                    externalSpec: 'ExtRef2',
+                    term: 'propagation',
+                    trefAliases: [],
+                    xrefAliases: [],
+                    sourceFiles: [
+                        { file: 'composability.md', type: 'xref' },
+                        { file: 'greenhouse.md', type: 'xref' },
+                        { file: 'soil.md', type: 'xref' }
+                    ]
+                }
+            ] 
+        };
+
+        // Simulate: composability.md has been deleted
+        const fileContents = new Map([
+            ['greenhouse.md', '[[tref:ExtRef1,greenhouse]] [[xref:ExtRef2,propagation]]'],
+            ['soil.md', '[[xref:ExtRef1,greenhouse]] [[xref:ExtRef2,propagation]]']
+        ]);
+
+        // Filter out xtrefs that don't exist in any file (none should be removed)
+        allXTrefs.xtrefs = allXTrefs.xtrefs.filter(xtref =>
+            require('./pipeline/references/xtref-utils').isXTrefInAnyFile(xtref, fileContents)
+        );
+
+        // Clean up sourceFiles arrays to remove deleted files
+        allXTrefs.xtrefs.forEach(xtref => {
+            if (xtref.sourceFiles && Array.isArray(xtref.sourceFiles)) {
+                const currentFiles = Array.from(fileContents.keys());
+                xtref.sourceFiles = xtref.sourceFiles.filter(sf => 
+                    currentFiles.includes(sf.file)
+                );
+            }
+        });
+
+        // Verify: composability.md should be removed from all sourceFiles arrays
+        expect(allXTrefs.xtrefs.length).toBe(2);
+        
+        expect(allXTrefs.xtrefs[0].sourceFiles).toEqual([
+            { file: 'greenhouse.md', type: 'tref' },
+            { file: 'soil.md', type: 'xref' }
+        ]);
+        
+        expect(allXTrefs.xtrefs[1].sourceFiles).toEqual([
+            { file: 'greenhouse.md', type: 'xref' },
+            { file: 'soil.md', type: 'xref' }
+        ]);
+    });
+
+    it('should handle case where all files are deleted for a term', () => {
+        // Setup: Create a term with only one source file
+        const allXTrefs = { 
+            xtrefs: [
+                {
+                    externalSpec: 'ExtRef1',
+                    term: 'orphan-term',
+                    trefAliases: [],
+                    xrefAliases: [],
+                    sourceFiles: [
+                        { file: 'deleted-file.md', type: 'tref' }
+                    ]
+                }
+            ] 
+        };
+
+        // Simulate: All files deleted
+        const fileContents = new Map([
+            ['other-file.md', 'Some content without the orphan term']
+        ]);
+
+        // Filter out xtrefs that don't exist in any file
+        allXTrefs.xtrefs = allXTrefs.xtrefs.filter(xtref =>
+            require('./pipeline/references/xtref-utils').isXTrefInAnyFile(xtref, fileContents)
+        );
+
+        // This xtref should be completely removed since it doesn't exist in any file
+        expect(allXTrefs.xtrefs.length).toBe(0);
+    });
+});
+
 
 // Tests for extracting and collecting external references from markdown
 describe('addNewXTrefsFromMarkdown', () => {

package/src/install-from-boilerplate/boilerplate/gitignore

@@ -1,4 +1,4 @@
-node_modules
+node_modules/
 *.log
 dist
 *.bak
@@ -7,5 +7,5 @@ dist
 .env
 coverage
 build
-.history
+.history/
 /.cache/

package/src/install-from-boilerplate/boilerplate/menu-wrapper.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# This wrapper script checks if node_modules exists before attempting to run the menu
+# This ensures users get a helpful error message if they forgot to run npm install
+
+if [ ! -d "node_modules" ]; then
+    echo -e "\n⚠️  ERROR: node_modules directory not found."
+    echo -e "   Please run 'npm install' first to install dependencies.\n"
+    exit 1
+fi
+
+if [ ! -d "node_modules/spec-up-t" ]; then
+    echo -e "\n⚠️  ERROR: spec-up-t package not found in node_modules."
+    echo -e "   Please run 'npm install' to install dependencies.\n"
+    exit 1
+fi
+
+# Run the actual menu script
+bash ./node_modules/spec-up-t/src/install-from-boilerplate/menu.sh "$@"

package/src/install-from-boilerplate/boilerplate/specs.json

@@ -19,21 +19,18 @@
             "source": {
                 "host": "github",
                 "account": "trustoverip",
-                "repo": "spec-up-t-starter-pack",
-                "branch": "main"
+                "repo": "spec-up-t-starter-pack"
             },
             "external_specs": [
                 {
                     "external_spec": "ExtRef1",
                     "gh_page": "https://trustoverip.github.io/spec-up-t-demo-external-ref-1/",
-                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-1",
-                    "terms_dir": "spec/terms-definitions"
+                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-1"
                 },
                 {
                     "external_spec": "ExtRef2",
                     "gh_page": "https://trustoverip.github.io/spec-up-t-demo-external-ref-2/",
-                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-2",
-                    "terms_dir": "spec/terms-definitions"
+                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-2"
                 }
             ],
             "katex": false,

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

@@ -8,7 +8,7 @@ const configScriptsKeys = {
     "freeze": "node -e \"require('spec-up-t/src/freeze-spec-data.js')\"",
     "references": "node -e \"require('spec-up-t/src/pipeline/references/external-references-service.js')\"",
     "help": "cat ./node_modules/spec-up-t/src/install-from-boilerplate/help.txt",
-    "menu": "bash ./node_modules/spec-up-t/src/install-from-boilerplate/menu.sh",
+    "menu": "bash ./menu-wrapper.sh",
     "addremovexrefsource": "node --no-warnings -e \"require('spec-up-t/src/add-remove-xref-source.js')\"",
     "configure": "node --no-warnings -e \"require('spec-up-t/src/configure.js')\"",
     "healthCheck": "node --no-warnings ./node_modules/spec-up-t/src/health-check.js",

package/src/install-from-boilerplate/config-system-files.js

@@ -1,6 +1,7 @@
 const systemFiles = [
     'README.md',
     '.env.example',
+    'menu-wrapper.sh',
     '.github/workflows/menu.yml',
     '.github/workflows/set-gh-pages.yml',
     'assets/test.json',