spec-up-t 0.11.29 → 0.11.31

package/src/fix-markdown-files.js

@@ -0,0 +1,64 @@
+/**
+ * @file This file contains a function that adds a blank line at the end of all markdown files in a directory and its subdirectories, only if the blank line is missing.
+ * @author Kor Dwarshuis
+ * @version 1.0.0
+ * @since 2024-08-20
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Function to process markdown files in a directory recursively
+function processMarkdownFiles(directory) {
+    // Helper function to process a directory
+    function processDirectory(directory) {
+        // Read the contents of the directory
+        fs.readdir(directory, { withFileTypes: true }, (err, items) => {
+            if (err) {
+                console.error(`Error reading directory: ${err}`);
+                return;
+            }
+
+            // Loop through each item in the directory
+            items.forEach(item => {
+                const itemPath = path.join(directory, item.name);
+                if (item.isDirectory()) {
+                    // If the item is a directory, call processDirectory recursively
+                    processDirectory(itemPath);
+                } else if (item.isFile() && path.extname(item.name) === '.md') {
+                    // If the item is a markdown file, process it
+                    fs.readFile(itemPath, 'utf8', (err, data) => {
+                        if (err) {
+                            console.error(`Error reading file ${item.name}: ${err}`);
+                            return;
+                        }
+
+                        // Check if the file ends with a blank line
+                        if (!data.endsWith('\n')) {
+                            // If not, add a blank line at the end
+                            data += '\n';
+                            // Write the modified content back to the file
+                            fs.writeFile(itemPath, data, 'utf8', err => {
+                                if (err) {
+                                    console.error(`Error writing file ${item.name}: ${err}`);
+                                } else {
+                                    console.log(`Added blank line to ${item.name}`);
+                                }
+                            });
+                        }
+                    });
+                }
+            });
+        });
+    }
+
+    // Start processing from the given directory
+    processDirectory(directory);
+}
+
+const directoryPath = './spec';
+processMarkdownFiles(directoryPath);
+
+module.exports = {
+    processMarkdownFiles
+}

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
-    allXrefs.xrefs = allXrefs.xrefs.map(match => {
-        return match.trim();
+    // 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,44 +190,58 @@ function getXrefsData() {
         xref.repo = urlParts[2];
     });
 
-    allXrefs.xrefs.forEach(match => {
+    // 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 => {
                     const key = Object.keys(externalSpec)[0];
-                    if (key === match.externalSpec) {
-                        match.site = externalSpec[key];
+                    if (key === xref.externalSpec) {
+                        xref.site = externalSpec[key];
                     }
                 });
             }
         });
     });
 
-    async function fetchLatestCommitHashes() {
-        for (const match of allXrefs.xrefs) {
-            match.commitHash = await fetchLatestCommitHash(match);
+    // Loop through all xrefs and fetch the latest commit hash for each term and add it to the xref object
+    /* Example of xref after adding commitHash:
+        xref:  {
+            "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/",
+            "commitHash": [
+                "f66951f1d378490289caab9c51141b44a0438365"
+            ]
         }
-    }
+    */
 
     // 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
+};

package/spec/header.md

@@ -1,20 +0,0 @@
-## Status
-
-This is the first public review draft of the ToIP Glossary. It is also the first version published using the [Spec-Up specification editing utility](https://identity.foundation/spec-up/) developed by the [Decentralized Identity Foundation](http://identity.foundation/).
-
-## Copyright Notice
-
-This specification is subject to the **OWF Contributor License Agreement 1.0 - Copyright**
-available at
-[https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright).
-
-These terms are inherited from the [Technical Stack Working Group](https://wiki.trustoverip.org/display/HOME/Technology+Stack+Working+Group) at the Trust over IP (ToIP) Foundation. [Working Group Charter](https://trustoverip.org/wp-content/uploads/TSWG-2-Charter-Revision.pdf)
-
-
-## Terms of Use
-
-These materials are made available under and are subject to the [OWF CLA 1.0 - Copyright & Patent license](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright-and-patent). Any source code is made available under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt).
-
-THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series ("ToIP"), and its members and contributors (each of ToIP, its members and contributors, a "ToIP Party") expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user.
-
-IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/spec/introduction.md

@@ -1,32 +0,0 @@
-
-[//]: # (Pandoc Formatting Macros)
-
-[//]: # (::: introtitle)
-
-[//]: # (Introduction)
-
-[//]: # (:::)
-
-## Introduction
-
-The ToIP Glossary is a deliverable of the ToIP Concepts and Terminology Working Group. Its purpose is to promote shared understanding of terms and concepts across the many different working groups, communities, enterprises, and ecosystems who are collaborating to develop and deploy decentralized digital trust infrastructure.
-
-Contributions and feedback are encouraged from any stakeholder in this area of terminology.
-
-## Linking to this Glossary
-
-This glossary is designed to be both human and machine readable. All terms are listed alphabetically; acronyms are listed separately and linked to the fully expanded terms. Document authors can link directly to any term using standard web links and anchors following this syntax:
-
-  `https://trustoverip.org/ctwg-main-glossary#term:xxxxx`
-
-Where `xxxxx` is the term as it appears in the glossary, with any spaces are replaced by en-dashes (hyphens). For example, a link to the term `self-certifying identifer` would be:
-
-  `https://trustoverip.github.io/ctwg-main-glossary#self-certifiying-identifier`
-
-A specification document written using the [Decentralized Identity Foundation](http://identity.foundation/)'s open source [Spec-Up editor](https://identity.foundation/spec-up/) may create special external references to terms in this glossary using the Spec-Up `xref` tag following this syntax:
-
-  `[[xref: glossary, xxxxx]]`
-
-  Where `glossary` is the text label the document author assigns to the URL of a Web-accessible glossary, and `xxxxx` is the term as it appears in that glossary, with any spaces are replaced by en-dashes (hyphens). For example, a Spec-Up external reference to the term `self-certifying identifer` using the label `toip` for this glossary would look like this:
-
-  `[[xref: toip, self-certifying-identifier]]`

package/spec/referenced_glossaries.md

@@ -1,24 +0,0 @@
-## Referenced Glossaries
-
-[//]: # (Pandoc Formatting Macros)
-
-[//]: # (# Normative references)
-
-[//]: # (::: { #nrm:pdf2 .normref label="ISO 32000-2" })
-
-[//]: # (ISO 32000-2, *Document management --- Portable Document Format --- Part 2: PDF 2.0*)
-
-[//]: # (:::)
-
-The following glossaries were used as sources for some of the definitions in the ToIP Glossary. All source glossaries are cited in the definitions of each term.
-
-| Short Name | Source Glossary | URL |
-|------------|-----------------|-----|
-| Wikipedia | Wikipedia | https://www.wikipedia.org/ |
-| eSSIF-Lab | eSSIF-Lab Glossary | https://essif-lab.github.io/framework/docs/essifLab-glossary |
-| NIST-CSRC | NIST Computer Security Resource Center Glossary | https://csrc.nist.gov/glossary/ |
-| PEMC IGR | Kantara Privacy Enhancing Mobile Credentials Implementors Guidance Report | https://kantarainitiative.org/download/pemc-implementors-guidance-report/ |
-| W3C DID | W3C Decentralized Identifiers (DIDs) 1.0 | https://www.w3.org/TR/did-core/#terminology |
-| W3C VC | W3C VC Data Model 1.1 | https://www.w3.org/TR/vc-data-model/#terminology |
-| Ethereum | Ethereum.org Glossary | https://ethereum.org/ |
-| Merriam-Webster | Merriam-Webster Dictionary | https://www.merriam-webster.com/dictionary/ |

package/spec/terms_and_definitions.md

@@ -1,10 +0,0 @@
-
-[//]: # (Pandoc Formatting Macros)
-
-[//]: # (Portable Document Format)
-
-[//]: # (blank)
-
-[//]: # (: file format defined by ISO 32000-2)
-
-## Terms & Definitions

package/spec/title.md

@@ -1,38 +0,0 @@
-ToIP Glossary 
-==================
-
-**Specification Status**: Public Review Draft 01 (PR1)
-
-**Latest Draft:**
-
-* [Github Repository](https://github.com/trustoverip/ctwg-main-glossary)
-* [Submit/View Issues](https://github.com/trustoverip/ctwg-main-glossary/issues)
-* [Discussions](https://github.com/trustoverip/ctwg-main-glossary/discussions)
-
-**Editors:**
-
-- [Drummond Reed](https://github.com/talltree), [Gen](https://www.gendigital.com)
-- [Henk van Caan](https://github.com/henkvancann)
-
-**Contributors:**
-
-- [Darrell O'Donnell](https://github.com/darrellodonnell), [Continuum Loop Inc.](https://www.continuumloop.com/)
-- [Kevin Griffin](https://github.com/m00sey), [GLEIF](https://gleif.org)
-- [Kor Dwarshuis](https://github.com/kordwarshuis/)
-- [Neil Thomson] TODO
-- [Nicky Hickman] TODO
-- [Rieks Joosten] TODO
-- TODO
-
-**Participate:**
-
-~ [GitHub repo](https://github.com/trustoverip/ctwg-main-glossary)
-~ [Commit history](https://github.com/trustoverip/ctwg-main-glossary/commits/main)
-
-------------------------------------
-
-[//]: # (Pandoc Formatting Macros)
-
-[//]: # (\maketitle)
-
-[//]: # (\newpage)

package/spec/toc.md

@@ -1,4 +0,0 @@
-
-[//]: # (Pandoc Formatting Macros)
-
-[//]: # (\toc)