spec-up-t 0.11.30 → 0.11.32

package/index.js

@@ -7,6 +7,9 @@ module.exports = function(options = {}) {
     findExternalSpecByKey
   } = require('./references.js');
 
+  const { runJsonKeyValidatorSync } = require('./src/json-key-validator.js');
+  runJsonKeyValidatorSync();
+
   const { processMarkdownFiles } = require('./src/fix-markdown-files.js');
   processMarkdownFiles('./spec');
   

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "spec-up-t",
-  "version": "0.11.30",
+  "version": "0.11.32",
   "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": {
     "type": "git",
     "url": "git+https://github.com/blockchainbird/spec-up-t.git"
   },
-  "scripts": {
-    "edit": "node -e \"require('./index')()\"",
-    "render": "node -e \"require('./index')({ nowatch: true })\"",
-    "dev": "node -e \"require('./index')({ dev: true })\""
-  },
   "keywords": [
     "spec",
     "specs",
@@ -56,6 +51,7 @@
     "merge-stream": "2.0.0",
     "pkg-dir": "4.2.0",
     "prismjs": ">=1.24.0",
+    "readline-sync": "^1.4.10",
     "yargs": "16.2.0"
   }
-}
+}

package/src/get-xrefs-data.js

@@ -5,25 +5,26 @@
  * @since 2024-06-09
  */
 
-// Get the current working directory
-
 const fs = require('fs-extra');
 const config = fs.readJsonSync('specs.json');
-const specDirectories = config.specs.map(spec => spec.spec_directory + '/' + spec.spec_terms_directory);
+
+// Collect all directories that contain files with a term and definition
+const specTermsDirectories = config.specs.map(spec => spec.spec_directory + '/' + spec.spec_terms_directory);
 
 // Create directory named “output” in the project root if it does not yet exist
 if (!fs.existsSync('output')) {
     fs.mkdirSync('output');
 }
 
-// Create directory named “output/xrefs” in the project root if it does not yet exist
+// Create directory named “output/xrefs-history” in the project root if it does not yet exist
 if (!fs.existsSync('output/xrefs-history')) {
     fs.mkdirSync('output/xrefs-history');
 }
 
 // Create a path for the output file in the project root
-const outputPath = 'output/xrefs-data.js';
-const outputPathTimeStamped = 'output/xrefs-history/xrefs-data-' + Date.now() + '.js';
+const outputPathJSON = 'output/xrefs-data.json';
+const outputPathJS = 'output/xrefs-data.js';
+const outputPathJSTimeStamped = 'output/xrefs-history/xrefs-data-' + Date.now() + '.js';
 
 function getXrefsData() {
     let allXrefs = {};
@@ -31,6 +32,22 @@ function getXrefsData() {
 
     // Function to fetch the latest commit hash of the file
     async function fetchLatestCommitHash(match) {
+        /* Example
+            console.log('match: ', match); ->
+            
+            match:  {
+                externalSpec: 'test-1',
+                term: 'Aal',
+                repoUrl: 'https://github.com/blockchainbird/spec-up-xref-test-1',
+                terms_dir: 'spec/term-definitions',
+                owner: 'blockchainbird',
+                repo: 'spec-up-xref-test-1',
+                site: 'https://blockchainbird.github.io/spec-up-xref-test-1/'
+            }
+        */
+
+        
+        
         try {
 
             if (match.repoUrl === undefined) {
@@ -60,9 +77,9 @@ function getXrefsData() {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
 
-            console.log(`Github API request for the term “${match.term}” was successful`);
+            console.log(`\nGithub API request for:\n  Term ${match.term},\n  Name: ${match.externalSpec}\n  Owner ${match.owner}\n  Repo ${match.repo}\nwas successful`);
 
-            // Extract JSON data from the response
+            // Extract JSON data from the response, see https://blockchainbird.github.io/spec-up-t-website/docs/various-roles/developers-guide/#example-of-api-response for example response
             const data = await response.json();
 
             // Check if there are any commits
@@ -72,22 +89,51 @@ function getXrefsData() {
                 return;
             }
 
-            // Process the last ten commits
-            const commits = data.slice(0, 1); // Get only the last commit
+            // Get only the last commit
+            const commits = data.slice(0, 1);
+            // Assign the fetched commit hash to the variable commitHash
             const commitHash = commits.map(commit => commit.sha);
             
-            console.log(`Commit hash found for the term “${match.term}”: `, commitHash);
-            return commitHash;
+            console.log(`\nCommit hash found for the term “${match.term}”: `, commitHash);
+
+
+            //TODO: Check if a term is in the JSON file and not in the markdown file. If so, remove the term from the JSON file.
+
+            // Check if the file exists
+            if (fs.existsSync(outputPathJSON)) {
+                // Read the JSON file
+                let currentXrefs = fs.readJsonSync(outputPathJSON);
+                // Check if the term is in the JSON file
+                currentXrefs.xrefs.forEach(xref => {
+                    // Check if the term is in the JSON file
+                    if (xref.term === match.term) {
+                        // If the term is in the JSON file, get the commit hash from the file and assign it to the variable commitHash. This is done to prevent the commit hash from being overwritten by the fetched commit hash. We want to keep the commit hash that was fetched at the time that the author looked it up.
+                        console.log(`\nThis external reference:\n Term: ${match.term}\n Name: ${match.externalSpec}\n Owner: ${match.owner}\n Repo: ${match.repo}\nis already referenced.
+                        `)
+
+                        // Give the commitHash from the JSON file to the commitHash variable
+                        commitHash = xref.commitHash;
+                    }
+                });
+            } else {
+                console.error(`File not found: ${outputPathJSON}`);
+            }
 
-            // return;
+            return commitHash;
         } catch (error) {
             console.error(`Failed to fetch commit hash for the term “${match.term}”:`, error);
         }
     }
 
+    async function fetchLatestCommitHashes() {
+        for (const xref of allXrefs.xrefs) {
+            xref.commitHash = await fetchLatestCommitHash(xref);
+        }
+    }
+
     // Go through all directories that contain files with a term and definition
-    console.log('All “spec_directory” found in specs.json: ', specDirectories);
-    specDirectories.forEach(specDirectory => {
+    console.log("All “spec_directory”'s found in specs.json: ", specTermsDirectories);
+    specTermsDirectories.forEach(specDirectory => {
         console.log(`Current spec_directory: `, specDirectory);
         // read directory
         fs.readdirSync(specDirectory).forEach(file => {
@@ -101,7 +147,7 @@ function getXrefsData() {
                     const xrefs = markdown.match(regex);
                     xrefs.forEach(xref => {
                         console.log(`Xref found in ${file}: `, xref);
-                        // example of xref: [[xref: PE, Holder]]
+                        // example of xref: [xref: test-1, Aal]
                         allXrefs.xrefs.add(xref);
                     });
                 }
@@ -113,26 +159,28 @@ function getXrefsData() {
 
     // Example output:
     // allXrefs.xrefs: [
-    //     '[[xref: PE, Holder]]',
     //     '[[xref: test-1, Aal]]',
     //     '[[xref: test-2, Abac]]'
     // ]
 
-    // remove “[[xref:” from the beginning of every value in allMatches
+    // The following steps create an array of objects with the keys “externalSpec” and “term” for each xref by splitting the xref string on the comma and removing the “[[xref:” and “]]” parts
+
+    // Step 1: remove “[[xref:” from the beginning of every value in allMatches
     allXrefs.xrefs = allXrefs.xrefs.map(xref => {
         return xref.replace(/\[\[xref:/, '');
     });
-    // remove “]]” from the end of every value in allMatches
+
+    // Step 2: remove “]]” from the end of every value in allMatches
     allXrefs.xrefs = allXrefs.xrefs.map(xref => {
         return xref.replace(/\]\]/, '');
     });
 
-    // trim every entry of allMatches
+    // Step 3: trim every entry of allMatches
     allXrefs.xrefs = allXrefs.xrefs.map(xref => {
         return xref.trim();
     });
 
-    // split every entry of allMatches on the first comma, replace the entry with an object that has two keys: one that contains everything before the comma and one that contains everything after the comma
+    // Step 4: split every entry of allMatches on the first comma, replace the entry with an object that has two keys: one that contains everything before the comma and one that contains everything after the comma
     allXrefs.xrefs = allXrefs.xrefs.map(xref => {
         let [externalSpec, term] = xref.split(/,/, 2);
         return {
@@ -143,12 +191,11 @@ function getXrefsData() {
 
     // Example output:
     // allXrefs.xrefs: [
-    //     { externalSpec: 'PE', term: 'Holder' },
     //     { externalSpec: 'test-1', term: 'Aal' },
     //     { externalSpec: 'test-2', term: 'Abac' }
     // ]
 
-
+    // Step 5: add the url and the dir where the terms are, to the xref object
     allXrefs.xrefs.forEach(xref => {
         config.specs.forEach(spec => {
             spec.external_specs_repos.forEach(repo => {
@@ -156,8 +203,8 @@ function getXrefsData() {
                 // Example external_specs_repos:
                 // "external_specs_repos": [
                 //     {
-                //         "external_spec": "PE",
-                //         "url": "https://github.com/decentralized-identity/presentation-exchange",
+                //         "external_spec": "test-1",
+                //         "url": "https://github.com/blockchainbird/spec-up-xref-test-1",
                 //         "terms_dir": "spec"
                 //     },
                 // …
@@ -170,6 +217,7 @@ function getXrefsData() {
         });
     });
 
+    // Step 6: add the owner and repo to the xref object
     allXrefs.xrefs.forEach(xref => {
         if (xref.repoUrl === undefined) {
             console.log('match.repoUrl is undefined');
@@ -181,15 +229,16 @@ function getXrefsData() {
         xref.repo = urlParts[2];
     });
 
+    // Step 7: add the site to the xref object
     allXrefs.xrefs.forEach(xref => {
         // loop through array of specs in config
         config.specs.forEach(spec => {
             if (spec.external_specs) {
                 // Example external_specs:
                 // "external_specs": [
-                //     {
-                //         "PE": "https://identity.foundation/presentation-exchange"
-                //     },
+                //      {
+                //          "test-1": "https://blockchainbird.github.io/spec-up-xref-test-1/"
+                //      }
                 // …
                 // ]
                 spec.external_specs.forEach(externalSpec => {
@@ -217,26 +266,48 @@ function getXrefsData() {
             ]
         }
     */
-    async function fetchLatestCommitHashes() {
-        for (const xref of allXrefs.xrefs) {
-            xref.commitHash = await fetchLatestCommitHash(xref);
-        }
-    }
 
     // Call the function and wait for it to complete before writing to the file
     fetchLatestCommitHashes().then(() => {
         // Convert allXrefsStr to a JSON string with indentation
         const allXrefsStr = JSON.stringify(allXrefs, null, 2);
 
+        // // Write the JSON code to a .json file
+        fs.writeFileSync(outputPathJSON, allXrefsStr, 'utf8');
+
         // Create the JS code for the assignment
         const stringReadyForFileWrite = `const allXrefs = ${allXrefsStr};`;
 
         // Write the JS code to a .js file
-        fs.writeFileSync(outputPath, stringReadyForFileWrite, 'utf8');
-        fs.writeFileSync(outputPathTimeStamped, stringReadyForFileWrite, 'utf8');
+        fs.writeFileSync(outputPathJS, stringReadyForFileWrite, 'utf8');
+        fs.writeFileSync(outputPathJSTimeStamped, stringReadyForFileWrite, 'utf8');
+    });
+}
+
+// Write function that removes an entry from xrefs-data.json and xrefs-data.js based on the term and externalSpec
+function removeXref(term, externalSpec) {
+    // Read the JSON file
+    let currentXrefs = fs.readJsonSync(outputPathJSON);
+
+    // Remove the entry from the JSON file
+    currentXrefs.xrefs = currentXrefs.xrefs.filter(xref => {
+        return !(xref.term === term && xref.externalSpec === externalSpec);
     });
+
+    // Convert the JSON object back to a JSON string
+    const currentXrefsStr = JSON.stringify(currentXrefs, null, 2);
+
+    // Write the JSON code to a .json file
+    fs.writeFileSync(outputPathJSON, currentXrefsStr, 'utf8');
+
+    // Create the JS code for the assignment
+    const stringReadyForFileWrite = `const allXrefs = ${currentXrefsStr};`;
+
+    // Write the JS code to a .js file
+    fs.writeFileSync(outputPathJS, stringReadyForFileWrite, 'utf8');
 }
 
 module.exports = {
-    getXrefsData
+    getXrefsData,
+    removeXref
 }

package/src/json-key-validator.js

@@ -0,0 +1,94 @@
+const fs = require('fs');
+const readlineSync = require('readline-sync');
+
+let errorFound = false;
+
+// Function to pause the script and wait for the ENTER key synchronously
+function pauseForEnterSync() {
+    readlineSync.question('Press ENTER to continue...');
+}
+
+function loadData() {
+    return JSON.parse(fs.readFileSync('./specs.json', 'utf8'));
+}
+
+function checkKeysSync(object, expectedKeys, parentKey = '') {
+    for (let key of expectedKeys) {
+        if (Array.isArray(object)) {
+            for (let [index, item] of object.entries()) {
+                checkKeysSync(item, expectedKeys, `${parentKey}[${index}]`);
+            }
+        } else if (typeof object === 'object') {
+            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/blockchainbird/spec-up-t-starter-pack/blob/main/spec-up-t-starterpack/specs.json`);
+                errorFound = true;
+                pauseForEnterSync(); // Pause synchronously
+            }
+            if (typeof expectedKeys[key] === 'object' && object[key]) {
+                checkKeysSync(object[key], expectedKeys[key], `${parentKey}.${key}`);
+            }
+        }
+    }
+}
+
+function runJsonKeyValidatorSync() {
+    const data = loadData();
+    const expectedKeys = {
+        specs: [
+            "title",
+            "spec_directory",
+            "spec_terms_directory",
+            "output_path",
+            "markdown_paths",
+            "logo",
+            "logo_link",
+            "source",
+            "external_specs",
+            "external_specs_repos",
+            "assets",
+            "katex",
+            "searchHighlightStyle"
+        ],
+        source: [
+            "host",
+            "account",
+            "repo"
+        ],
+        external_specs_repos: [
+            "external_spec",
+            "url",
+            "terms_dir"
+        ],
+        assets: [
+            "path",
+            "inject",
+            "module"
+        ]
+    };
+
+    for (let [index, spec] of data.specs.entries()) {
+        console.log(`   Checking spec #${index + 1}`);
+        checkKeysSync(spec, expectedKeys.specs, `specs[${index}]`);
+
+        if (spec.source) {
+            checkKeysSync(spec.source, expectedKeys.source, `specs[${index}].source`);
+        }
+
+        if (spec.external_specs_repos) {
+            checkKeysSync(spec.external_specs_repos, expectedKeys.external_specs_repos, `specs[${index}].external_specs_repos`);
+        }
+
+        // if (spec.assets) {
+        //     checkKeysSync(spec.assets, expectedKeys.assets, `specs[${index}].assets`);
+        // }
+    }
+
+    if (!errorFound) {
+        console.log('   All keys are present. No errors found. Continue…');
+    }
+}
+
+// Export the function to be used in other scripts
+module.exports = {
+    runJsonKeyValidatorSync
+};