spec-up-t 1.1.52 → 1.1.54

package/src/create-term-index.js

@@ -15,6 +15,8 @@
  * @since 2024-09-02
  */
 
+const { shouldProcessFile } = require('./utils/file-filter');
+
 function createTermIndex() {
     const fs = require('fs-extra');
     const path = require('path');
@@ -23,7 +25,7 @@ function createTermIndex() {
     const specTermDirectoryName = config.specs.map(spec => spec.spec_terms_directory);
     const outputPathJSON = path.join('output', 'term-index.json');
     const files = fs.readdirSync(path.join(specDirectories[0], specTermDirectoryName[0]))
-        .filter(file => !file.startsWith('_') && file.endsWith('.md'));
+        .filter(shouldProcessFile);
 
     const filePaths = files.map(file => specTermDirectoryName[0] + '/' + file);
 

package/src/create-term-relations.js

@@ -5,9 +5,11 @@
  * @since 2024-06-22
  */
 
+
 const fs = require('fs-extra');
 const path = require('path');
 const config = fs.readJsonSync('specs.json');
+const { shouldProcessFile } = require('./utils/file-filter');
 
 const specTermDirectoryName = config.specs.map(spec => spec.spec_directory + '/' + spec.spec_terms_directory);
 
@@ -41,7 +43,7 @@ function createTermRelations() {
         // read directory
         fs.readdirSync(specDirectory).forEach(file => {
             // read file
-            if (file.endsWith('.md')) {
+            if (shouldProcessFile(file)) {
                 const markdown = fs.readFileSync(`${specDirectory}/${file}`, 'utf8');
 
                 let regexDef = /\[\[def:.*?\]\]/g;

package/src/fix-markdown-files.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { shouldProcessFile } = require('./utils/file-filter');
 
 // Function to process markdown files in a directory recursively
 function fixMarkdownFiles(directory) {
@@ -15,7 +16,7 @@ function fixMarkdownFiles(directory) {
                 if (item.isDirectory()) {
                     // If the item is a directory, call processDirectory recursively
                     processDirectory(itemPath);
-                } else if (item.isFile() && path.extname(item.name) === '.md') {
+                } else if (item.isFile() && shouldProcessFile(item.name)) {
                     try {
                         // Read the file synchronously
                         let data = fs.readFileSync(itemPath, 'utf8');

package/src/markdown-it-extensions.js

@@ -94,6 +94,111 @@ module.exports = function (md, templates = {}) {
     if (targetIndex !== -1 && idx > targetIndex && !classAdded) {
       tokens[idx].attrPush(['class', 'terms-and-definitions-list']);
       classAdded = true;
+
+      /* Sort terms and definitions alphabetically
+      Sort dt/dd pairs case-insensitively based on dt content
+
+      1: Token-based Markdown Processing: Spec-Up-T uses a token-based approach to parse and render Markdown. When Markdown is processed, it's converted into a series of tokens that represent different elements (like dt_open, dt_content, dt_close, dd_open, dd_content, dd_close). We're not dealing with simple strings but with structured tokens.
+
+      2: Preserving Relationships: When sorting terms, we need to ensure that each definition term (<dt>) stays connected to its corresponding definition description (<dd>). It's not as simple as sorting an array of strings - we're sorting complex structures.
+
+      3: Implementation Details: The implementation includes:
+
+      - Finding the terminology section in the document
+      - Collecting term starts, ends, and their contents
+      - Creating a sorted index based on case-insensitive comparisons
+      - Rebuilding the token array in the correct order
+      - Ensuring all relationships between terms and definitions are preserved
+      - Handling special cases and edge conditions
+
+      The complexity is unavoidable because:
+
+      - We're working with the markdown-it rendering pipeline, not just manipulating DOM
+      - The terms and definitions exist as tokens before they become HTML
+      - We need to preserve all the token relationships while reordering
+      - We're intercepting the rendering process to modify the token structure
+
+      If we were just sorting DOM elements after the page rendered, it would be simpler. But by doing the sorting during the Markdown processing, we ensure the HTML output is correct from the beginning, which is more efficient and leads to better performance.
+      */
+      let dtStartIndices = [];
+      let dtEndIndices = [];
+      let dtContents = [];
+
+      // First pass: collect all dt blocks and their contents
+      for (let i = idx + 1; i < tokens.length; i++) {
+        if (tokens[i].type === 'dl_close') {
+          break;
+        }
+        if (tokens[i].type === 'dt_open') {
+          const startIdx = i;
+          let content = '';
+
+          // Find the end of this dt block and capture its content
+          for (let j = i + 1; j < tokens.length; j++) {
+            if (tokens[j].type === 'dt_close') {
+              dtStartIndices.push(startIdx);
+              dtEndIndices.push(j);
+              dtContents.push(content.toLowerCase()); // Store lowercase for case-insensitive sorting
+              break;
+            }
+            // Collect the content inside the dt (including spans with term IDs)
+            if (tokens[j].content) {
+              content += tokens[j].content;
+            }
+          }
+        }
+      }
+
+      // Create indices sorted by case-insensitive term content
+      const sortedIndices = dtContents.map((_, idx) => idx)
+        .sort((a, b) => dtContents[a].localeCompare(dtContents[b]));
+
+      // Reorder the tokens based on the sorted indices
+      if (sortedIndices.length > 0) {
+        // Create a new array of tokens
+        const newTokens = tokens.slice(0, idx + 1); // Include dl_open
+
+        // For each dt/dd pair in sorted order
+        for (let i = 0; i < sortedIndices.length; i++) {
+          const originalIndex = sortedIndices[i];
+          const dtStart = dtStartIndices[originalIndex];
+          const dtEnd = dtEndIndices[originalIndex];
+
+          // Add dt tokens
+          for (let j = dtStart; j <= dtEnd; j++) {
+            newTokens.push(tokens[j]);
+          }
+
+          // Find and add dd tokens
+          let ddFound = false;
+          for (let j = dtEnd + 1; j < tokens.length; j++) {
+            if (tokens[j].type === 'dt_open' || tokens[j].type === 'dl_close') {
+              break;
+            }
+            if (tokens[j].type === 'dd_open') {
+              ddFound = true;
+            }
+            if (ddFound) {
+              newTokens.push(tokens[j]);
+              if (tokens[j].type === 'dd_close') {
+                break;
+              }
+            }
+          }
+        }
+
+        // Add the closing dl token
+        for (let i = idx + 1; i < tokens.length; i++) {
+          if (tokens[i].type === 'dl_close') {
+            newTokens.push(tokens[i]);
+            break;
+          }
+        }
+
+        // Replace the old tokens with the new sorted ones
+        tokens.splice(idx, newTokens.length, ...newTokens);
+      }
+      // END Sort terms and definitions alphabetically
     }
 
     let lastDdIndex = -1;

package/src/prepare-tref.js

@@ -22,6 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const dedent = require('dedent');
+const { shouldProcessFile } = require('./utils/file-filter');
 
 function getLocalXTrefContent(externalSpec, term) {
     const filePath = path.join('output', 'xtrefs-data.json');
@@ -58,7 +59,7 @@ function prepareTref(directory) {
                 if (item.isDirectory()) {
                     // If the item is a directory, call processDirectory recursively
                     processDirectory(itemPath);
-                } else if (item.isFile() && path.extname(item.name) === '.md') {
+                } else if (item.isFile() && shouldProcessFile(item.name)) {
                     try {
                         // Read the file synchronously
                         let data = fs.readFileSync(itemPath, 'utf8');

package/src/utils/file-filter.js

@@ -0,0 +1,36 @@
+/**
+ * @file Utility functions for filtering files consistently across the codebase
+ */
+
+/**
+ * Checks if a file is a Markdown file (ends with .md)
+ * @param {string} filename - The filename to check
+ * @returns {boolean} - True if the file is a Markdown file, false otherwise
+ */
+function isMarkdownFile(filename) {
+    return filename.endsWith('.md');
+}
+
+/**
+ * Checks if a file is hidden/excluded (starts with underscore)
+ * @param {string} filename - The filename to check
+ * @returns {boolean} - True if the file is hidden/excluded, false otherwise
+ */
+function isNotHiddenFile(filename) {
+    return !filename.startsWith('_');
+}
+
+/**
+ * Checks if a file should be processed (is a Markdown file and not hidden)
+ * @param {string} filename - The filename to check
+ * @returns {boolean} - True if the file should be processed, false otherwise
+ */
+function shouldProcessFile(filename) {
+    return isMarkdownFile(filename) && isNotHiddenFile(filename);
+}
+
+module.exports = {
+    isMarkdownFile,
+    isNotHiddenFile,
+    shouldProcessFile
+};

package/src/utils/isLineWithDefinition.js

@@ -1,13 +1,8 @@
-async function isLineWithDefinition(line) {
-    line = line.trim();
-    // Check if the string starts with `[[def:` and ends with `]]`
-    if (line.startsWith('[[def:') && line.endsWith(']]')) {
-        // console.log('String starts with `[[def:` and ends with `]]`');
-        return true;
-    } else {
-        // console.log('String does not start with `[[def:` or end with `]]`');
-        return false;
-    }
+function isLineWithDefinition(line) {
+    if (!line || typeof line !== 'string') return false;
+
+    // Check if the line starts with [[def: and contains ]]
+    return line.startsWith('[[def:') && line.includes(']]');
 }
 
 exports.isLineWithDefinition = isLineWithDefinition;

package/readme.md

@@ -1,10 +0,0 @@
-# Spec-Up-T
-
-<div align="center">
-
-<img src="./static/specup_logo.png">
-
-<h2 style="display: block; margin: 0 auto; text-align: center;">Markdown » Spec-Up</h2>
-</div>
-
-There is a [special website that documents everything regarding Spec-Up-T](https://blockchainbird.github.io/spec-up-t-website/).

package/src/collectExternalReferences/checkRateLimit.js

@@ -1,17 +0,0 @@
-// Function to check the rate limit of the GitHub API
-function checkRateLimit(response) {
-    const remaining = response.headers.get('X-RateLimit-Remaining');
-    const reset = response.headers.get('X-RateLimit-Reset');
-
-    if (response.status === 403 && remaining === '0') {
-        const resetTime = new Date(reset * 1000);
-        console.error(`❌ Github API rate limit exceeded. Try again after ${resetTime}. See https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token for more info.`);
-        return true;
-    } else if (remaining !== null) {
-        console.log(`ℹ️ Github API rate limit: ${remaining} requests remaining. See https://blockchainbird.github.io/spec-up-t-website/docs/getting-started/github-token for more info.`);
-    } else {
-        console.warn(`ℹ️ Unable to determine rate limit status. Check your GitHub API token and network connection.`);
-    }
-    return false;
-}
-exports.checkRateLimit = checkRateLimit;

package/src/collectExternalReferences/setupFetchHeaders.js

@@ -1,14 +0,0 @@
-function setupFetchHeaders(GITHUB_API_TOKEN) {
-    const fetchHeaders = {
-        'Accept': 'application/vnd.github.v3+json'
-    };
-
-    if (GITHUB_API_TOKEN) {
-        fetchHeaders['Authorization'] = `token ${GITHUB_API_TOKEN}`;
-    } else {
-        console.log('ℹ️ There is no GitHub token set up. Therefore, you are more likely to be at your limit of GitHub API requests. If you run into the limit, create a token and search the documentation on this topic.');
-    }
-
-    return fetchHeaders;
-}
-exports.setupFetchHeaders = setupFetchHeaders;