spec-up-t 0.11.30 → 0.11.31

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.31",
   "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 = {};
@@ -62,7 +63,7 @@ function getXrefsData() {
 
             console.log(`Github API request for the term “${match.term}” was 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
@@ -85,9 +86,15 @@ function getXrefsData() {
         }
     }
 
+    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 +108,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 +120,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 +152,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 +164,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 +178,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 +190,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,23 +227,21 @@ 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');
     });
 }
 

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
+};