spec-up-t 1.3.1 → 1.4.0

package/src/init.js

@@ -1,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const Logger = require('./utils/logger');
 const outputDir = path.join(process.cwd(), '.cache');
 const initFlagPath = path.join(outputDir, 'init.flag');
 
@@ -20,9 +21,9 @@ async function initialize() {
         // Create the init flag file
         await fs.writeFile(initFlagPath, 'Initialization completed.');
 
-        console.log('Initialization complete.');
+        Logger.success('Initialization complete.');
     } catch (error) {
-        console.error(`Initialization failed: ${error.message}`);
+        Logger.error(`Initialization failed: ${error.message}`);
     }
 }
 

package/src/install-from-boilerplate/add-gitignore-entries.js

@@ -1,4 +1,5 @@
 const fs = require('fs').promises;
+const Logger = require('../utils/logger');
 
 /**
  * Reads the content of a file or returns an empty string if the file does not exist.
@@ -42,9 +43,9 @@ async function updateGitignore(gitignorePath, filesToAdd) {
         // Write the updated content back to the .gitignore file
         await fs.writeFile(gitignorePath, updatedGitignoreContent, 'utf8');
 
-        console.log('✅ Updated .gitignore file');
+        Logger.success('Updated .gitignore file');
     } catch (error) {
-        console.error('❌ Error updating .gitignore:', error.message);
+        Logger.error('Error updating .gitignore:', error.message);
     }
 }
 

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

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const Logger = require('../utils/logger');
 
 /**
  * Adds scripts to the package.json file.
@@ -15,7 +16,7 @@ function addScriptsKeys(scriptKeys, overwriteKeys = {}) {
     // Read the package.json file
     fs.readFile(packageJsonPath, 'utf8', (err, data) => {
         if (err) {
-            console.error('❌ Error reading package.json:', err);
+            Logger.error('Error reading package.json:', err);
             return;
         }
 
@@ -38,13 +39,13 @@ function addScriptsKeys(scriptKeys, overwriteKeys = {}) {
             // Write the updated package.json back to disk
             fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), 'utf8', (err) => {
                 if (err) {
-                    console.error('❌ Error writing package.json:', err);
+                    Logger.error('Error writing package.json:', err);
                 } else {
-                    console.log('✅ Scripts added to package.json successfully!');
+                    Logger.success('Scripts added to package.json successfully!');
                 }
             });
         } catch (parseError) {
-            console.error('❌ Error parsing package.json:', parseError);
+            Logger.error('Error parsing package.json:', parseError);
         }
     });
 }

package/src/install-from-boilerplate/boilerplate/README.md

@@ -1,5 +1,5 @@
 # Documentation
 
-Read more about Spec-Up-T in the [documentation](https://blockchainbird.github.io/spec-up-t-website/).
+Read more about Spec-Up-T in the [documentation](https://trustoverip.github.io/spec-up-t-website/).
 
 Written: 2025-02-27T15:38

package/src/install-from-boilerplate/boilerplate/spec/example-markup-in-markdown.md

@@ -245,7 +245,7 @@ graph TD
 ```
 </pre>
 
-```js
+```chart
 {
   "type": "pie",
   "data": {

package/src/install-from-boilerplate/boilerplate/spec/spec-head.md

@@ -2,6 +2,6 @@
 
 ## Intro
 
-This is a default Spec-Up-T installation. Find information on the [Spec-Up-T documentation website](https://blockchainbird.github.io/spec-up-t-website/).
+This is a default Spec-Up-T installation. Find information on the [Spec-Up-T documentation website](https://trustoverip.github.io/spec-up-t-website/).
 
 This is a demo site for Spec-Up-T. The subject matter – gardening and related terms – is used purely as an example to demonstrate how the system works. You can replace these demo terms and definitions with your own content to suit your documentation needs.

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

@@ -19,7 +19,8 @@
             "source": {
                 "host": "github",
                 "account": "trustoverip",
-                "repo": "spec-up-t-starter-pack"
+                "repo": "spec-up-t-starter-pack",
+                "branch": "main"
             },
             "external_specs": [
                 {

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

@@ -2,11 +2,11 @@ const configScriptsKeys = {
     "edit": "node -e \"require('spec-up-t')()\"",
     "render": "node --no-warnings -e \"require('spec-up-t/index.js')({ nowatch: true })\"",
     "dev": "node -e \"require('spec-up-t')({ dev: true })\"",
-    "collectExternalReferences": "node --no-warnings -e \"require('spec-up-t/src/collect-external-references.js').collectExternalReferences()\"",
+    "collectExternalReferences": "node --no-warnings -e \"require('spec-up-t/src/pipeline/references/collect-external-references.js').collectExternalReferences()\"",
     "topdf": "node -e \"require('spec-up-t/src/create-pdf.js')\"",
     "todocx": "node -e \"require('spec-up-t/src/create-docx.js')\"",
-    "freeze": "node -e \"require('spec-up-t/src/freeze.js')\"",
-    "references": "node -e \"require('spec-up-t/src/references.js')\"",
+    "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",
     "addremovexrefsource": "node --no-warnings -e \"require('spec-up-t/src/add-remove-xref-source.js')\"",

package/src/install-from-boilerplate/copy-boilerplate.js

@@ -1,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const Logger = require('../utils/logger');
 
 function copyBoilerplate() {
     const sourceDir = path.join(__dirname, './', 'boilerplate');
@@ -16,7 +17,7 @@ function copyBoilerplate() {
     const gitignoreDestPath = path.join(__dirname, '../../../../', '.gitignore');
     fs.renameSync(gitignorePath, gitignoreDestPath);
 
-    console.log('✅ Copied spec-up-t-boilerplate to current directory');
+    Logger.success('Copied spec-up-t-boilerplate to current directory');
 }
 
 module.exports = copyBoilerplate;

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

@@ -1,6 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const { systemFiles } = require('./config-system-files.js');
+const Logger = require('../utils/logger');
 
 /**
  * Copies system files from the boilerplate directory to the root of the project.
@@ -18,13 +19,13 @@ function copySystemFiles() {
 
         try {
             fs.cpSync(srcPath, destPath, { recursive: true });
-            console.log(`✅ Copied ${item} to ${destPath}`);
+            Logger.success(`Copied ${item} to ${destPath}`);
         } catch (error) {
-            console.error(`❌ Failed to copy ${item} to ${destPath}:`, error);
+            Logger.error(`Failed to copy ${item} to ${destPath}:`, error);
         }
     });
 
-    console.log('✅ Copied system files to current directory');
+    Logger.success('Copied system files to current directory');
 }
 
 module.exports = copySystemFiles;

package/src/install-from-boilerplate/custom-update.js

@@ -10,4 +10,15 @@ addScriptsKeys(configScriptsKeys, configOverwriteScriptsKeys);
 copySystemFiles();
 updateGitignore(gitIgnoreEntries.gitignorePath, gitIgnoreEntries.filesToAdd);
 
-console.log("✅ Custom update done");
+const Logger = require('../utils/logger');
+
+// We can use this file to do any custom updates during post-install.
+const customUpdate = () => {
+    // Custom logic here
+    // ...
+}
+
+// Call custom update
+customUpdate();
+
+Logger.success("Custom update done");

package/src/install-from-boilerplate/help.txt

@@ -1,6 +1,6 @@
 ===
 
-For help go to: https://blockchainbird.github.io/spec-up-t-website
+For help go to: https://trustoverip.github.io/spec-up-t-website
 
 ===
 

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

@@ -21,7 +21,7 @@ function handle_choice() {
         echo "  ${options[index]}"
         echo -e "  ************************************\n\n"
         show_progress
-        ${options[index + 1]}
+        "${options[index + 1]}"
     else
         clear
         echo -e "\n\n  ************************************"
@@ -69,7 +69,7 @@ function prompt_input() {
 
 function do_add_content() {
     clear
-    echo -e "\n\n\n   ********************\n\n\n   You can start adding your content to the markdown files in the "spec" directory.\n\n   You can do this by editing local files in an editor or by going to your repository on GitHub.\n\n   More info: https://blockchainbird.github.io/spec-up-t-website/docs/various-roles/content-authors-guide/introduction\n\n\n   ********************"  
+    echo -e "\n\n\n   ********************\n\n\n   You can start adding your content to the markdown files in the "spec" directory.\n\n   You can do this by editing local files in an editor or by going to your repository on GitHub.\n\n   More info: https://trustoverip.github.io/spec-up-t-website/docs/various-roles/content-authors-guide/introduction\n\n\n   ********************"  
 }
 
 function do_render() { clear; npm run render; }
@@ -83,14 +83,14 @@ function do_freeze() { clear; npm run freeze; }
 
 function do_help() {
     clear
-    echo -e "\n\n\n   You will be redirected to the documentation website\n\n   (https://blockchainbird.github.io/spec-up-t-website/)."
+    echo -e "\n\n\n   You will be redirected to the documentation website\n\n   (https://trustoverip.github.io/spec-up-t-website/)."
     sleep 2
     if [[ "$OSTYPE" == "darwin"* ]]; then
-        open "https://blockchainbird.github.io/spec-up-t-website/"
+        open "https://trustoverip.github.io/spec-up-t-website/"
     elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
-        xdg-open "https://blockchainbird.github.io/spec-up-t-website/"
+        xdg-open "https://trustoverip.github.io/spec-up-t-website/"
     elif [[ "$OSTYPE" == "cygwin" || "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-        start "https://blockchainbird.github.io/spec-up-t-website/"
+        start "https://trustoverip.github.io/spec-up-t-website/"
     else
         echo "Unsupported OS."
     fi

package/src/json-key-validator.js

@@ -10,6 +10,7 @@
 
 const fs = require('fs');
 const readlineSync = require('readline-sync');
+const Logger = require('./utils/logger');
 
 let errorFound = false;
 
@@ -25,6 +26,11 @@ function loadData() {
 
 // This function recursively checks if the required keys are present in the object
 function checkKeysSync(object, expectedKeys, parentKey = '') {
+    // Guard against undefined or non-iterable expected key definitions so the validator fails gracefully instead of throwing.
+    if (!Array.isArray(expectedKeys)) {
+        return;
+    }
+
     for (let key of expectedKeys) {
         if (Array.isArray(object)) {
             // If the object is an array, check each item within the array
@@ -34,7 +40,7 @@ function checkKeysSync(object, expectedKeys, parentKey = '') {
         } else if (typeof object === 'object') {
             // If the key is missing from the object, log an error
             if (!(key in object)) {
-                console.error(`❌ Error: Missing key '${key}' in ${parentKey}\n   We cannot guarantee that Spec-Up-T will work properly.\n   Here is an example specs.json file:\n   https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-boilerplate/specs.json`);
+                Logger.error(`Error: Missing key '${key}'\n   We cannot guarantee that Spec-Up-T will work properly.\n   Here is an example specs.json file:\n   https://github.com/trustoverip/spec-up-t-starter-pack/blob/main/spec-up-t-boilerplate/specs.json`);
                 errorFound = true;
                 pauseForEnterSync(); // Pause synchronously to allow user to acknowledge the error
             }
@@ -61,7 +67,7 @@ function runJsonKeyValidatorSync() {
             "logo",
             "logo_link",
             "source",
-            "external_specs"
+            // "external_specs"
             // "assets"  // Commented out: We no longer check for 'assets' in the specs object
         ],
         source: [
@@ -69,12 +75,12 @@ function runJsonKeyValidatorSync() {
             "account",
             "repo"
         ],
-        external_specs: [
-            "gh_page",
-            "external_spec",
-            "url",
-            "terms_dir"
-        ],
+        // external_specs: [
+        //     "gh_page",
+        //     "external_spec",
+        //     "url",
+        //     "terms_dir"
+        // ],
         // Removed the 'assets' block entirely, as it's no longer part of the required keys:
         // assets: [
         //     "path",
@@ -85,7 +91,7 @@ function runJsonKeyValidatorSync() {
 
     // Iterate over each spec entry in the specs array from the JSON file
     for (let [index, spec] of data.specs.entries()) {
-        console.log(`ℹ️ Checking spec #${index + 1}`);
+        Logger.info(`Checking spec #${index + 1}`);
 
         // Check for keys defined in expectedKeys.specs
         checkKeysSync(spec, expectedKeys.specs, `specs[${index}]`);
@@ -96,7 +102,7 @@ function runJsonKeyValidatorSync() {
         }
 
         // Check for keys inside the 'external_specs' array, if present
-        if (spec.external_specs) {
+        if (spec.external_specs && Array.isArray(expectedKeys.external_specs)) {
             checkKeysSync(spec.external_specs, expectedKeys.external_specs, `specs[${index}].external_specs`);
         }
 
@@ -108,7 +114,7 @@ function runJsonKeyValidatorSync() {
 
     // If no errors were found, print a success message
     if (!errorFound) {
-        console.log('✅ All keys are present. No errors found. Continuing…');
+        Logger.success('All keys are present. No errors found. Continuing…');
     }
 }
 

package/src/markdown-it/README.md

@@ -0,0 +1,207 @@
+# Markdown-it Extensions
+
+This directory contains the refactored markdown-it extensions used by the spec-up-t system. The extensions have been broken down into focused, well-documented modules to improve maintainability and understanding.
+
+## Module Overview
+
+### Core Philosophy
+
+The markdown-it library uses a token-based rendering system where:
+
+- **Tokens** represent different parts of the markdown (paragraphs, headers, tables, etc.)
+- **Renderer rules** are functions that convert tokens to HTML
+- **Inline rules** process inline elements during parsing
+- **Plugins** extend the parser with custom functionality
+
+Our extensions override default renderer rules and add custom inline parsing rules to implement spec-up-specific functionality.
+
+## Modules
+
+### 1. `table-enhancement.js`
+
+**Purpose**: Enhances table rendering with Bootstrap styling and responsive wrappers.
+
+**Features**:
+
+- Adds Bootstrap CSS classes (`table`, `table-striped`, `table-bordered`, `table-hover`)
+- Wraps tables in responsive containers (`table-responsive-md`)
+- Preserves existing classes while adding new ones
+
+**How it works**: Overrides `table_open` and `table_close` renderer rules.
+
+### 2. `template-tag-syntax.js`
+
+**Purpose**: Processes custom template-tag syntax like `[[def:term]]`, `[[tref:spec,term]]`, etc.
+
+**Features**:
+
+- Parses `[[type:arg1,arg2]]` syntax during markdown processing
+- Creates template tokens for later rendering
+- Supports extensible template-tag handlers
+- Integrates with the escape mechanism
+
+**How it works**:
+
+- Adds an inline ruler (`templates_ruler`) to detect and parse template-tag syntax
+- 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`
+
+**Purpose**: Advanced processing of definition lists for terminology and reference management.
+
+**Features**:
+
+- **Smart Classification**: Distinguishes between terminology lists and reference lists
+- **Term Type Detection**: Identifies local terms (`[[def:term]]`) vs external terms (`[[tref:spec,term]]`)
+- **Quality Control**: Removes empty `<dt>` elements that cause rendering issues
+- **Section-Aware**: Only applies terminology styling after the terminology section marker
+
+**How it works**:
+
+- Overrides `dl_open`, `dt_open`, and `dt_close` renderer rules
+- Uses helper functions to analyze token structure and content
+- Applies CSS classes based on term types and context
+
+### 5. `index.js`
+
+**Purpose**: Main orchestrator that applies all enhancements in the correct order.
+
+**Features**:
+
+- Single entry point for all markdown-it extensions
+- Maintains dependency order between modules
+- Provides both unified and individual module access
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const MarkdownIt = require('markdown-it');
+const applyMarkdownItExtensions = require('./markdown-it');
+
+const md = new MarkdownIt();
+const templates = [
+  {
+    filter: type => type === 'def',
+    render: (token, type, term) => `<span id="term:${term}">${term}</span>`
+  }
+];
+
+applyMarkdownItExtensions(md, templates);
+const html = md.render('[[def:example-term]]');
+```
+
+### Individual Module Usage
+
+```javascript
+const applyTableEnhancements = require('./markdown-it/table-enhancement');
+const applyTemplateTagSyntax = require('./markdown-it/template-tag-syntax');
+
+// Apply only table enhancements
+applyTableEnhancements(md);
+
+// Apply only template-tag syntax with custom handlers
+applyTemplateTagSyntax(md, templates);
+```
+
+## Template System
+
+The template-tag system processes custom syntax like `[[type:args]]` in markdown. Template-tags are defined as objects with:
+
+- `filter(type)`: Function that returns true if this handler processes the given type
+- `parse(token, type, ...args)`: Optional preprocessing function called during parsing
+- `render(token, type, ...args)`: Function that returns HTML string for rendering
+
+### Example Template-Tag Handler
+
+```javascript
+{
+  filter: type => type.match(/^def$/),
+  parse: (token, type, term, alias) => {
+    // Preprocessing during markdown parsing
+    definitions.push([term, alias]);
+    return `<span id="term:${term.replace(/\s+/g, '-').toLowerCase()}">${term}</span>`;
+  },
+  render: (token, type, ...args) => {
+    // Final rendering (if parse didn't handle it)
+    return token.content;
+  }
+}
+```
+
+## Definition List Processing
+
+The definition list module implements sophisticated logic for handling terminology:
+
+### List Classification
+
+- **Terminology Lists**: Get `terms-and-definitions-list` class
+- **Reference Lists**: Keep existing classes (e.g., `reference-list`)
+- **Section-Aware**: Only processes lists after `terminology-section-start` marker
+
+### Term Classification
+
+- **Local Terms** (`[[def:term]]`): Get `term-local` class
+- **External Terms** (`[[tref:spec,term]]`): Get `term-external` class
+- **Regular Terms**: No special class
+
+### Quality Control
+
+- **Empty Elements**: Removes `<dt>` elements with no content
+- **Spec References**: Avoids styling bibliographic references as terminology
+
+## Development Guidelines
+
+### Adding New Modules
+
+1. Create a focused module in this directory
+2. Follow the existing naming pattern (`feature-name.js`)
+3. Export a single function that takes a markdown-it instance
+4. Add comprehensive documentation with examples
+5. Update `index.js` to include the new module
+
+### Code Quality
+
+- Keep cognitive complexity below 15
+- Add extensive comments for markdown-it concepts
+- Use descriptive function and variable names
+- Extract helper functions for complex logic
+- Write tests for new functionality
+
+### SonarQube Compliance
+
+All modules must pass SonarQube analysis without issues. The refactoring specifically addresses:
+
+- Reduced cognitive complexity through modularization
+- Better code organization and separation of concerns
+- Comprehensive documentation for maintainability
+
+## Backward Compatibility
+
+The main `markdown-it-extensions.js` file maintains complete backward compatibility by delegating to the new modular system. Existing code can continue to use the original interface without changes.
+
+## Testing
+
+Run the full test suite to ensure all functionality works correctly:
+
+```bash
+npm test
+```
+
+Individual modules can be tested by importing and using them directly in test files.
+
+Please remember to run `gulp compile` after making changes to client-side assets, and test on a separate test machine before deployment.