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

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/config-scripts-keys.js

@@ -11,7 +11,7 @@ const configScriptsKeys = {
     "menu": "bash ./node_modules/spec-up-t/src/install-from-boilerplate/menu.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 -e \"require('spec-up-t/src/health-check.js')\"",
+    "healthCheck": "node --no-warnings ./node_modules/spec-up-t/src/health-check.js",
     "custom-update": "npm update && node -e \"require('spec-up-t/src/install-from-boilerplate/custom-update.js')\""
 };
 

package/src/markdown-it/README.md

@@ -46,19 +46,7 @@ Our extensions override default renderer rules and add custom inline parsing rul
 - Creates template tokens with parsed information
 - Provides a renderer rule to convert template tokens to HTML
 
-### 3. `link-enhancement.js`
-
-**Purpose**: Adds path-based attributes to links for CSS styling and JavaScript targeting.
-
-**Features**:
-
-- Extracts domain and path segments from URLs
-- Adds `path-0`, `path-1`, etc. attributes to anchor tags
-- Special handling for auto-detected links (linkify)
-
-**How it works**: Overrides `link_open` and `link_close` renderer rules.
-
-### 4. `definition-lists.js`
+### 3. `definition-lists.js`
 
 **Purpose**: Advanced processing of definition lists for terminology and reference management.
 
@@ -75,7 +63,7 @@ Our extensions override default renderer rules and add custom inline parsing rul
 - Uses helper functions to analyze token structure and content
 - Applies CSS classes based on term types and context
 
-### 5. `index.js`
+### 4. `index.js`
 
 **Purpose**: Main orchestrator that applies all enhancements in the correct order.
 

package/src/markdown-it/index.js

@@ -12,7 +12,6 @@
  * 
  * - TABLE ENHANCEMENT: Bootstrap styling and responsive wrappers
  * - TEMPLATE-TAG SYNTAX: Custom [[template-tag:args]] syntax processing
- * - LINK ENHANCEMENT: Path-based attributes for links
  * - DEFINITION LISTS: Advanced terminology and reference list handling
  * 
  * This modular approach makes the code more maintainable and easier to
@@ -22,7 +21,6 @@
 // Import all the specialized enhancement modules
 const applyTableEnhancements = require('./table-enhancement');
 const applyTemplateTagSyntax = require('./template-tag-syntax');
-const applyLinkEnhancements = require('./link-enhancement');
 const applyDefinitionListEnhancements = require('./definition-lists');
 
 /**
@@ -64,10 +62,7 @@ function applyMarkdownItExtensions(md, templates = []) {
   // 2. Template-tag syntax - should be applied early as other modules may depend on it
   applyTemplateTagSyntax(md, templates);
   
-  // 3. Link enhancements - independent, can be applied anytime
-  applyLinkEnhancements(md);
-  
-  // 4. Definition lists - depends on template-tag syntax for term type detection
+  // 3. Definition lists - depends on template-tag syntax for term type detection
   applyDefinitionListEnhancements(md);
   
   // The markdown-it instance is now fully enhanced and ready for use
@@ -79,5 +74,4 @@ module.exports = applyMarkdownItExtensions;
 // Also export individual modules for fine-grained control if needed
 module.exports.tableEnhancements = applyTableEnhancements;
 module.exports.templateTagSyntax = applyTemplateTagSyntax;
-module.exports.linkEnhancements = applyLinkEnhancements;
 module.exports.definitionLists = applyDefinitionListEnhancements;

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

@@ -14,6 +14,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 Logger = require('../utils/logger.js');
 
 /**
  * Extracts the current file from token content for source tracking
@@ -32,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
  */
@@ -44,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':
@@ -129,17 +132,41 @@ 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
  * Uses primaryDisplayTerm concept: shows first alias if available, otherwise shows the term itself
  * @param {Object} config - Configuration containing external specs
  * @param {Object} token - The markdown-it token
- * @returns {string} HTML anchor element linking to external term
+ * @returns {string} HTML anchor element linking to external term or error span if unresolved
  */
 function parseXref(config, token) {
   const externalSpec = findExternalSpecByKey(config, token.info.args[0]);
-  const url = externalSpec?.gh_page || '#';
+  
+  // If external spec cannot be found, return error indicator
+  if (!externalSpec) {
+    return `<span class="no-xref-found-message" title="External spec '${token.info.args[0]}' not found in configuration">xref cannot be resolved</span>`;
+  }
+
   const termName = token.info.args[1];
   const aliases = token.info.args.slice(2).filter(Boolean); // Get all aliases after the term
   const term = termName.replace(whitespace.oneOrMore, '-').toLowerCase();
@@ -148,8 +175,11 @@ function parseXref(config, token) {
   // Determine the primary display term (first alias if available, otherwise original term)
   const primaryDisplayTerm = aliases.length > 0 ? aliases[0] : termName;
 
+  // Build the href attribute using the external spec's gh_page
+  const href = `${externalSpec.gh_page}#term:${term}`;
+
   // Build link attributes with both local and external href capabilities
-  let linkAttributes = `class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}" href="${url}#term:${term}"`;
+  let linkAttributes = `class="x-term-reference term-reference" data-local-href="#term:${token.info.args[0]}:${term}" href="${href}"`;
 
   // Add tooltip content if term definition is available
   if (xrefTerm && xrefTerm.content) {
@@ -262,6 +292,13 @@ function processXTrefObject(xtref) {
     if (allAliases.length > 0) {
       xtrefObject.firstXrefAlias = allAliases[0];
     }
+    
+    // Log error if xref has more than one alias
+    // xref should only have 0 or 1 alias, unlike tref which supports multiple aliases
+    if (allAliases.length > 1) {
+      const extraAliases = allAliases.slice(1).join(', ');
+      Logger.error(`Invalid xref syntax: [[xref: ${xtrefObject.externalSpec}, ${xtrefObject.term}, ${allAliases.join(', ')}]] has ${allAliases.length} aliases. Only the first alias "${allAliases[0]}" will be used. Extra aliases ignored: ${extraAliases}.`);
+    }
   }
 
   return xtrefObject;
@@ -282,6 +319,7 @@ module.exports = {
   createTemplateTagParser,
   // Export individual functions for testing purposes
   parseDef,
+  parseIref,
   parseXref,
   parseTref,
   parseRef,

package/src/pipeline/postprocessing/definition-list-postprocessor.js

@@ -65,7 +65,8 @@ function sortDefinitionTermsInHtml(html) {
   });
 
   // Return the modified HTML
-  return dom.serialize();
+  // Extract only the body's innerHTML to avoid wrapping in <html><head></head><body> tags
+  return dom.window.document.body.innerHTML;
 }
 
 /**
@@ -340,7 +341,8 @@ function fixDefinitionListStructure(html) {
   }
 
   // Return the fixed HTML
-  return dom.serialize();
+  // Extract only the body's innerHTML to avoid wrapping in <html><head></head><body> tags
+  return dom.window.document.body.innerHTML;
 }
 
 module.exports = {

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

@@ -13,6 +13,7 @@ const fs = require('fs-extra');
 const readlineSync = require('readline-sync');
 
 const Logger = require('../../utils/logger');
+const messageCollector = require('../../utils/message-collector');
 const { shouldProcessFile } = require('../../utils/file-filter');
 const { getCurrentBranch } = require('../../utils/git-info');
 const { addNewXTrefsFromMarkdown, isXTrefInAnyFile } = require('./xtref-utils');
@@ -24,7 +25,8 @@ const { processXTrefObject } = require('../../parsers/template-tag-parser');
  * automated callers of `collectExternalReferences` continue to receive a fully rendered spec.
  */
 function renderSpecification() {
-    require('../../../index.js')({ nowatch: true });
+    // Pass skipClear to preserve messages from collectExternalReferences
+    require('../../../index.js')({ nowatch: true, skipClear: true });
 }
 
 /**
@@ -44,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;
     }
 
@@ -63,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;
     }
 
@@ -116,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';
         }
     });
@@ -151,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},
    
@@ -193,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;
         }
 
@@ -209,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;
     }
 
@@ -232,7 +258,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
     );
 
     fileContents.forEach((content, filename) => {
-        addNewXTrefsFromMarkdown(content, allXTrefs, filename, processXTrefObject);
+        addNewXTrefsFromMarkdown(content, allXTrefs, filename, processXTrefObject, externalSpecsRepos);
     });
 
     extendXTrefs(config, allXTrefs.xtrefs);
@@ -242,9 +268,17 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
 /**
  * Public entry point for the external reference collection stage.
  *
- * @param {{ pat?: string }} options - Optional overrides (GitHub PAT).
+ * @param {{ pat?: string, collectMessages?: boolean }} options - Optional overrides (GitHub PAT, message collection).
  */
 function collectExternalReferences(options = {}) {
+    // Start collecting messages if requested
+    const shouldCollectMessages = options.collectMessages !== false; // Collect by default
+
+    if (shouldCollectMessages) {
+        messageCollector.clearMessages();
+        messageCollector.startCollecting('collectExternalReferences');
+    }
+
     const config = fs.readJsonSync('specs.json');
     const normalizedConfig = normalizeSpecConfiguration(config, {
         noSpecsMessage: 'No specs defined in specs.json. Nothing to collect.'
@@ -252,6 +286,10 @@ function collectExternalReferences(options = {}) {
 
     // Bail out immediately if the specs.json file lacks the required specs collection.
     if (!normalizedConfig) {
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages();
+        }
         return;
     }
 
@@ -259,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.
@@ -268,7 +309,16 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'No external_specs array found on the first spec entry in specs.json. External reference collection is skipped.'
         );
-        renderSpecification();
+
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return;
     }
 
@@ -277,7 +327,16 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'The external_specs array in specs.json is empty. Add external repositories to collect external references.'
         );
-        renderSpecification();
+
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return;
     }
 
@@ -287,15 +346,40 @@ function collectExternalReferences(options = {}) {
     if (pipeline && typeof pipeline.then === 'function') {
         return pipeline
             .then(result => {
-                renderSpecification();
-                return result;
+                if (shouldCollectMessages) {
+                    messageCollector.stopCollecting();
+                    return messageCollector.saveMessages().then(path => {
+                        Logger.success(`Console messages saved to: ${path}`);
+                        renderSpecification();
+                        return result;
+                    });
+                } else {
+                    renderSpecification();
+                    return result;
+                }
             })
             .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 {
-        renderSpecification();
+        if (shouldCollectMessages) {
+            messageCollector.stopCollecting();
+            messageCollector.saveMessages().then(path => {
+                Logger.success(`Console messages saved to: ${path}`);
+                renderSpecification();
+            });
+        } else {
+            renderSpecification();
+        }
         return pipeline;
     }
 }