spec-up-t 1.6.2 → 1.6.3

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/spec/terms-definitions/composability.md

@@ -1,3 +1,5 @@
-[[tref: KERISuite, composability ]]
+[[tref: ExtRef1, greenhouse]]
 
-~ Note: composability is not the same as compostability.
+~ Note: This is a tref example. The term "greenhouse" is imported from the ExtRef1 external glossary (focused on greenhouse and irrigation concepts).
+
+~ See also: [[xref: ExtRef2, propagation]] for plant propagation from ExtRef2.

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

@@ -0,0 +1,5 @@
+[[tref: ExtRef2, dormancy]]
+
+~ Note: This is a tref example. The term "dormancy" is imported from the ExtRef2 external glossary (focused on plant lifecycle and propagation concepts).
+
+~ See also: [[xref: ExtRef1, perennial]] for perennial plants from ExtRef1.

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

@@ -0,0 +1,5 @@
+[[tref: ExtRef1, greenhouse]]
+
+~ Note: This is a tref example. The term "greenhouse" is imported from the ExtRef1 external glossary (focused on greenhouse and irrigation concepts).
+
+~ See also: [[xref: ExtRef2, propagation]] for plant propagation from ExtRef2.

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

@@ -4,8 +4,10 @@
 
 ~ Refs examples: [[ref: Compost]], [[ref: Mulch]], [[ref: Fertilizer]].
 
-~ Xref example: [[xref: KERISuite, composability ]]
+~ Xref examples from external gardening glossaries: 
+~ - From ExtRef1 (greenhouse focus): [[xref: ExtRef1, greenhouse]], [[xref: ExtRef1, irrigation]]
+~ - From ExtRef2 (lifecycle focus): [[xref: ExtRef2, dormancy]], [[xref: ExtRef2, propagation]]
 
-~ This Xref example does not work: [[xref: does-not-exist, Foo]]
+~ Note: The term "soil" exists in ExtRef1 and ExtRef2 with different definitions focused on their respective themes.
 
 ~ Soil quality affects water retention, nutrient availability, and plant health. Amending soil with compost or mulch can improve its structure and fertility. Fertilizer may be added to supplement nutrients as needed.

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

@@ -19,33 +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": "vLEI",
-                    "gh_page": "https://henkvancann.github.io/vlei-glossary/",
-                    "url": "https://github.com/henkvancann/vlei-glossary",
-                    "terms_dir": "spec/terms-definitions"
+                    "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"
                 },
                 {
-                    "external_spec": "KERISuite",
-                    "gh_page": "https://weboftrust.github.io/kerisuite-glossary/",
-                    "url": "https://github.com/weboftrust/kerisuite-glossary",
-                    "terms_dir": "spec/terms-definitions"
-                },
-                {
-                    "external_spec": "ToIP",
-                    "gh_page": "https://glossary.trustoverip.org/",
-                    "url": "https://github.com/trustoverip/ctwg-main-glossary",
-                    "terms_dir": "spec/terms-definitions"
-                },
-                {
-                    "external_spec": "GenIT",
-                    "gh_page": "https://trustoverip.github.io/ctwg-general-glossary/",
-                    "url": "https://github.com/trustoverip/ctwg-general-glossary",
-                    "terms_dir": "spec/terms-definitions"
+                    "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"
                 }
             ],
             "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',

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

@@ -253,10 +253,22 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
         });
     });
 
+    // Filter out xtrefs that don't exist in any current file
     allXTrefs.xtrefs = allXTrefs.xtrefs.filter(existingXTref =>
         isXTrefInAnyFile(existingXTref, fileContents)
     );
 
+    // Clean up sourceFiles arrays to remove deleted files
+    // This ensures that if a file is deleted, its entry is removed from all sourceFiles arrays
+    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)
+            );
+        }
+    });
+
     fileContents.forEach((content, filename) => {
         addNewXTrefsFromMarkdown(content, allXTrefs, filename, processXTrefObject, externalSpecsRepos);
     });

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

@@ -19,7 +19,7 @@ function validateReferences(references, definitions, render) {
   if (unresolvedRefs.length > 0) {
     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',
+      hint: 'Add [[def: term]] definitions or [[tref: repo, term]] transclusion for these terms or alter existing definitions, optionally by adding aliases, in your terminology files, or check for typos in [[ref: term]] references',
       details: `Count: ${unresolvedRefs.length} unresolved term(s)`
     });
   }
@@ -281,10 +281,18 @@ function extractTermsFromHtml(externalSpec, html) {
           const classArray = dtClasses ? dtClasses.split(/\s+/).filter(Boolean) : [];
           const termClasses = classArray.filter(cls => cls === 'term-local' || cls === 'term-external');
 
-          const dd = $termElement.next('dd');
+          // Extract ALL consecutive <dd> elements following this <dt>
+          // Terms can have multiple <dd> blocks for extended definitions
+          const ddElements = [];
+          let nextElement = $termElement.next();
+          while (nextElement.length > 0 && nextElement[0].tagName === 'dd') {
+            ddElements.push(nextElement);
+            nextElement = nextElement.next();
+          }
 
-          if (dd.length > 0) {
-            const ddContent = $.html(dd); // Store the complete DD content once
+          if (ddElements.length > 0) {
+            // Combine all <dd> elements into a single HTML string
+            const ddContent = ddElements.map(dd => $.html(dd)).join('\n'); // Store the complete DD content
 
             // Create a term object for each ID found in this dt element
             // This handles cases where one term definition has multiple aliases

package/src/pipeline/rendering/render-spec-document.js

@@ -10,7 +10,7 @@ const path = require('path');
 const { fetchExternalSpecs, validateReferences, mergeXrefTermsIntoAllXTrefs } = require('../references/external-references-service.js');
 const { processEscapedTags, restoreEscapedTags } = require('../preprocessing/escape-placeholder-utils.js');
 const { sortDefinitionTermsInHtml, fixDefinitionListStructure } = require('../postprocessing/definition-list-postprocessor.js');
-const { getGithubRepoInfo } = require('../../utils/git-info.js');
+const { getGithubRepoInfo, getCurrentBranch } = require('../../utils/git-info.js');
 const { templateTags } = require('../../utils/regex-patterns.js');
 
 const { createScriptElementWithXTrefDataForEmbeddingInHtml, applyReplacers } = require('./render-utils.js');
@@ -37,6 +37,9 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
     // Add universal timestamp in ISO 8601 format for template injection
     const universalTimestamp = date.toISOString();
 
+    // Get the branch name from which the index.html was generated
+    const buildBranch = getCurrentBranch();
+
     // Read all markdown files into an array
     const docs = await Promise.all(
       (spec.markdown_paths || ['spec.md']).map(_path =>
@@ -162,6 +165,7 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
       externalSpecsList: externalSpecsList,
       currentDate: currentDate,
       universalTimestamp: universalTimestamp,
+      buildBranch: buildBranch,
       githubRepoInfo: getGithubRepoInfo(spec)
     });
 

package/templates/template.html

@@ -137,15 +137,6 @@
         <!-- Right-aligned elements -->
         <div class="d-flex align-items-center service-menu d-print-none">
 
-            <!-- Settings side menu -->
-            <button id="repo_settings" class="btn btn-sm btn-outline-secondary ms-2" type="button"
-                data-bs-toggle="offcanvas" data-bs-target="#offcanvasSettings" aria-controls="offcanvasSettings">
-                <svg class="bi" width="1em" height="1em" aria-hidden="true">
-                    <use href="#gear-wide-connected"></use>
-                </svg>
-                <span class="visually-hidden">Settings</span>
-            </button>
-
             <!-- Dark / Light theme selector -->
             <div class="dropdown bd-mode-toggle">
                 <button
@@ -247,6 +238,16 @@
         </div>
     </div>
 
+    <!-- Menu toggle button - hamburger icon fixed at right edge for slide-in panel -->
+    <button id="repo_settings" class="btn btn-sm btn-outline-secondary menu-toggle-btn d-print-none" type="button"
+        data-bs-toggle="offcanvas" data-bs-target="#offcanvasSettings" aria-controls="offcanvasSettings"
+        title="Open menu">
+        <svg class="bi" width="1.25em" height="1.25em" aria-hidden="true">
+            <use href="#list"></use>
+        </svg>
+        <span class="visually-hidden">Open menu</span>
+    </button>
+
     <div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasSettings" aria-labelledby="offcanvasSettingsLabel">
         <div class="offcanvas-header">
             <h5 class="offcanvas-title mt-0" id="offcanvasSettingsLabel">Settings</h5>
@@ -293,7 +294,39 @@
                 ${externalSpecsList}
             </div>
             <hr>
-            <p class="ps-3 pe-3" id="w3c-state">W3C Recommendation, ${currentDate}</p>
+            <!-- External Reference Changes Report Section -->
+            <div class="ps-3 pe-3" id="external-ref-changes-section" style="display: none;">
+                <div class="d-flex justify-content-between align-items-center mb-2">
+                    <p class="mb-0 fw-bold">External Reference Changes:</p>
+                    <span id="external-ref-changes-badge" class="badge bg-warning text-dark">0</span>
+                </div>
+                <p class="small text-muted mb-2">Terms whose definitions have changed since the last build:</p>
+                <div id="external-ref-changes-container" class="external-ref-changes-report">
+                    <!-- Report table will be populated by JavaScript -->
+                </div>
+                <div id="external-ref-validation-status" class="small text-muted mt-2">
+                    <i class="bi bi-hourglass-split me-1"></i>
+                    Validating external references...
+                </div>
+            </div>
+            <hr id="external-ref-changes-divider" style="display: none;">
+            <p class="d-none ps-3 pe-3" id="w3c-state">W3C Recommendation, ${currentDate}</p>
+            <!-- Build Information Section -->
+            <div class="ps-3 pe-3">
+                <p class="mb-2 fw-bold">Build Information:</p>
+                <div id="build-info" class="small text-muted">
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-calendar-event me-2"></i>
+                        <time class="timestamp" datetime="${universalTimestamp}">
+                            Generated: ${universalTimestamp}
+                        </time>
+                    </div>
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-signpost-split me-2"></i>
+                        <span>Source branch: <strong>${buildBranch}</strong></span>
+                    </div>
+                </div>
+            </div>
         </div>
     </div>