spec-up-t 1.0.71 → 1.0.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "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": {

package/src/get-xrefs-data.js

@@ -29,62 +29,84 @@ const outputPathJSON = 'output/xrefs-data.json';
 const outputPathJS = 'output/xrefs-data.js';
 const outputPathJSTimeStamped = 'output/xrefs-history/xrefs-data-' + Date.now() + '.js';
 
-
-function addAllXrefs(GITHUB_API_TOKEN) {
-    // Set headers for GitHub API requests. Include an authorization token if provided.
+function setupFetchHeaders(GITHUB_API_TOKEN) {
     const fetchHeaders = {
         'Accept': 'application/vnd.github.v3+json'
     };
 
-    // If GITHUB_API_TOKEN is present, it adds an Authorization header to the fetchHeaders object with the value set to token ${GITHUB_API_TOKEN}. This header is used to authenticate requests to the GitHub API, allowing the user to make authenticated requests which have higher rate limits compared to unauthenticated requests.
     if (GITHUB_API_TOKEN) {
         fetchHeaders['Authorization'] = `token ${GITHUB_API_TOKEN}`;
     } else {
         console.log('\n   SPEC-UP-T: 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.\n');
     }
 
-    // Function to check the rate limit of the GitHub API
-    function checkRateLimit(response) {
-        if (response.status === 403 && response.headers.get('X-RateLimit-Remaining') === '0') {
-            const resetTime = new Date(response.headers.get('X-RateLimit-Reset') * 1000);
-            console.error(`\n   SPEC-UP-T: Github API rate limit exceeded. Try again after ${resetTime}. See https://blockchainbird.github.io/spec-up-t-website/docs/github-token/ for more info.` + "\n");
-            return true;
-        } else {
-            console.log(`\n   SPEC-UP-T: Github API rate limit: ${response.headers.get('X-RateLimit-Remaining')} requests remaining. See https://blockchainbird.github.io/spec-up-t-website/docs/github-token/ for more info.` + "\n");
-        }
-        return false;
+    return fetchHeaders;
+}
+
+// Function to check the rate limit of the GitHub API
+function checkRateLimit(response) {
+    if (response.status === 403 && response.headers.get('X-RateLimit-Remaining') === '0') {
+        const resetTime = new Date(response.headers.get('X-RateLimit-Reset') * 1000);
+        console.error(`\n   SPEC-UP-T: Github API rate limit exceeded. Try again after ${resetTime}. See https://blockchainbird.github.io/spec-up-t-website/docs/github-token/ for more info.` + "\n");
+        return true;
+    } else {
+        console.log(`\n   SPEC-UP-T: Github API rate limit: ${response.headers.get('X-RateLimit-Remaining')} requests remaining. See https://blockchainbird.github.io/spec-up-t-website/docs/github-token/ for more info.` + "\n");
     }
+    return false;
+}
 
-    // Function to fetch term information from GitHub, including commit hash and content.
-    async function fetchTermInfoFromGithub(xref) {
-        try {
-            // prerequisite: filename should be the term in the match object with spaces replaced by dashes and all lowercase
-            //TODO: Loop through all markdown files to find the term and get the filename, instead of assuming that the filename is the term with spaces replaced by dashes and all lowercase
-            const url = `https://api.github.com/repos/${xref.owner}/${xref.repo}/commits?path=${xref.terms_dir}/${xref.term.replace(/ /g, '-').toLowerCase()}.md&per_page=1`;
-            const response = await fetch(url, { headers: fetchHeaders });
-
-            // Check for rate limit before proceeding
-            if (checkRateLimit(response)) {
-                return;
+// Function to fetch term information from GitHub, including commit hash and content.
+async function fetchTermInfoFromGithub(GITHUB_API_TOKEN, xref) {
+    try {
+        // prerequisite: filename should be the term in the match object with spaces replaced by dashes and all lowercase
+        //TODO: Loop through all markdown files to find the term and get the filename, instead of assuming that the filename is the term with spaces replaced by dashes and all lowercase
+        const url = `https://api.github.com/repos/${xref.owner}/${xref.repo}/commits?path=${xref.terms_dir}/${xref.term.replace(/ /g, '-').toLowerCase()}.md&per_page=1`;
+        const response = await fetch(url, { headers: setupFetchHeaders(GITHUB_API_TOKEN) });
+
+        // Check for rate limit before proceeding
+        if (checkRateLimit(response)) {
+            return;
+        }
+
+        if (response.ok) {
+            const data = await response.json();
+            if (data.length > 0) {
+                const commitHash = data[0].sha;
+                const content = await fetchFileContentFromCommit(GITHUB_API_TOKEN, xref.owner, xref.repo, commitHash, `${xref.terms_dir}/${xref.term.replace(/ /g, '-').toLowerCase()}.md`);
+                return { commitHash, content };
             }
+        } else {
+            console.error(`\n   SPEC-UP-T: Failed to fetch commit hash for ${xref.term}: ${response.statusText}\n`);
+            return { commitHash: null, content: null };
+        }
+    } catch (error) {
+        console.error(`\n   SPEC-UP-T: Error fetching data for term ${xref.term}: ${error.message}\n`);
+    }
+    return null;
+}
 
-            if (response.ok) {
-                const data = await response.json();
-                if (data.length > 0) {
-                    const commitHash = data[0].sha;
-                    const content = await fetchFileContentFromCommit(xref.owner, xref.repo, commitHash, `${xref.terms_dir}/${xref.term.replace(/ /g, '-').toLowerCase()}.md`);
-                    return { commitHash, content };
-                }
-            } else {
-                console.error(`\n   SPEC-UP-T: Failed to fetch commit hash for ${xref.term}: ${response.statusText}\n`);
-                return { commitHash: null, content: null };
+// Function to fetch the content of a file from a specific commit in a GitHub repository.
+async function fetchFileContentFromCommit(GITHUB_API_TOKEN, owner, repo, commitHash, filePath) {
+    try {
+        const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitHash}?recursive=1`;
+        const treeResponse = await fetch(treeUrl, { headers: setupFetchHeaders(GITHUB_API_TOKEN) });
+
+        if (treeResponse.ok) {
+            const treeData = await treeResponse.json();
+            const file = treeData.tree.find(item => item.path === filePath);
+            if (file) {
+                const fileContentResponse = await fetch(file.url);
+                const fileContentData = await fileContentResponse.json();
+                return Buffer.from(fileContentData.content, 'base64').toString('utf-8');
             }
-        } catch (error) {
-            console.error(`\n   SPEC-UP-T: Error fetching data for term ${xref.term}: ${error.message}\n`);
         }
-        return null;
+    } catch (error) {
+        console.error(`\n   SPEC-UP-T: Error fetching file content: ${error.message}\n`);
     }
+    return null;
+}
 
+function updateXrefs(GITHUB_API_TOKEN) {
     // Function to extend xref objects with additional information, such as repository URL and directory information.
     function extendXrefs(config, xrefs) {
         if (config.specs[0].external_specs_repos) {
@@ -125,56 +147,53 @@ function addAllXrefs(GITHUB_API_TOKEN) {
         });
     }
 
-    // Function to fetch the content of a file from a specific commit in a GitHub repository.
-    async function fetchFileContentFromCommit(owner, repo, commitHash, filePath) {
-        try {
-            const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitHash}?recursive=1`;
-            const treeResponse = await fetch(treeUrl, { headers: fetchHeaders });
-
-            if (treeResponse.ok) {
-                const treeData = await treeResponse.json();
-                const file = treeData.tree.find(item => item.path === filePath);
-                if (file) {
-                    const fileContentResponse = await fetch(file.url);
-                    const fileContentData = await fileContentResponse.json();
-                    return Buffer.from(fileContentData.content, 'base64').toString('utf-8');
-                }
-            }
-        } catch (error) {
-            console.error(`\n   SPEC-UP-T: Error fetching file content: ${error.message}\n`);
-        }
-        return null;
-    }
-
-    // Initialize an object to store all xrefs. If the output JSON file exists, load its data.
+    // Initialize an object to store all xrefs.
     let allXrefs = { xrefs: [] };
 
+    // If the output JSON file exists, load its data.
     if (fs.existsSync(outputPathJSON)) {
         const existingXrefs = fs.readJsonSync(outputPathJSON);
         allXrefs = existingXrefs && existingXrefs.xrefs ? existingXrefs : { xrefs: [] };
     }
 
-    // Loop through each directory and file, extracting xrefs from markdown files.
+    // Function to check if an xref is in the markdown content
+    function isXrefInMarkdown(xref, markdownContent) {
+        const regex = new RegExp(`\\[\\[xref:${xref.term}\\]\\]`, 'g');
+        const result = regex.test(markdownContent);
+        return result;
+    }
+
+    // Collect all markdown content
+    let allMarkdownContent = '';
+
     specTermsDirectories.forEach(specDirectory => {
         fs.readdirSync(specDirectory).forEach(file => {
             if (file.endsWith('.md')) {
                 const markdown = fs.readFileSync(`${specDirectory}/${file}`, 'utf8');
-                const regex = /\[\[xref:.*?\]\]/g;
-                if (regex.test(markdown)) {
-                    const xrefs = markdown.match(regex);
-                    xrefs.forEach(xref => {
-                        const newXrefObj = processXref(xref);
-                        if (!allXrefs.xrefs.some(existingXref =>
-                            existingXref.term === newXrefObj.term && existingXref.externalSpec === newXrefObj.externalSpec)) {
-                            allXrefs.xrefs.push(newXrefObj);
-                        }
-                    });
-                }
+                allMarkdownContent += markdown;
             }
         });
     });
 
-    // Function to process and clean up xref strings, returning an object with `externalSpec` and `term` properties.
+    // Remove existing entries if not in the combined markdown content
+    allXrefs.xrefs = allXrefs.xrefs.filter(existingXref => {
+        return isXrefInMarkdown(existingXref, allMarkdownContent);
+    });
+
+    // Add new entries if they are in the markdown
+    const regex = /\[\[xref:.*?\]\]/g;
+    if (regex.test(allMarkdownContent)) {
+        const xrefs = allMarkdownContent.match(regex);
+        xrefs.forEach(xref => {
+            const newXrefObj = processXref(xref);
+            if (!allXrefs.xrefs.some(existingXref =>
+                existingXref.term === newXrefObj.term && existingXref.externalSpec === newXrefObj.externalSpec)) {
+                allXrefs.xrefs.push(newXrefObj);
+            }
+        });
+    };
+
+    // Function to process and clean up xref strings found in the markdown file, returning an object with `externalSpec` and `term` properties.
     function processXref(xref) {
         let [externalSpec, term] = xref.replace(/\[\[xref:/, '').replace(/\]\]/, '').trim().split(/,/, 2);
         return {
@@ -186,10 +205,16 @@ function addAllXrefs(GITHUB_API_TOKEN) {
     // Extend each xref with additional data and fetch commit information from GitHub.
     extendXrefs(config, allXrefs.xrefs);
 
+
+    /* 
+        Function to fetch all term information from GitHub. The function will not fetch the commit hash again if an entry already contains a commit hash.
+
+        It checks if the xref object already has a commitHash and content.If both are present, it skips fetching the term information from GitHub. This ensures that existing commit hashes are not overwritten.
+    */
     async function fetchAllTermsInfoFromGithub() {
         for (let xref of allXrefs.xrefs) {
             if (!xref.commitHash || !xref.content) {
-                const fetchedData = await fetchTermInfoFromGithub(xref);
+                const fetchedData = await fetchTermInfoFromGithub(GITHUB_API_TOKEN, xref);
                 if (fetchedData) {
                     xref.commitHash = fetchedData.commitHash;
                     xref.content = fetchedData.content;
@@ -260,8 +285,49 @@ function removeXref(term, externalSpec) {
     return messages;
 }
 
-// Export the addAllXrefs and removeXref functions for use in other modules.
+function addXref(term, externalSpec) {
+    let messages = [];
+
+    try {
+        // Read the JSON file
+        let currentXrefs = fs.readJsonSync(outputPathJSON);
+
+        // Check if the term and externalSpec exist
+        const entryExists = currentXrefs.xrefs.some(xref => xref.term === term && xref.externalSpec === externalSpec);
+
+        if (entryExists) {
+            messages.push(`\n   SPEC-UP-T: Entry with term "${term}" and externalSpec "${externalSpec}" already exists.\n`);
+            return messages;
+        }
+
+        // Add the entry to the JSON file
+        currentXrefs.xrefs.push({ term, 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');
+
+        messages.push(`\n   SPEC-UP-T: Entry with term "${term}" and externalSpec "${externalSpec}" added.\n`);
+
+        // Run the render function to update the HTML file
+        require('../index.js')({ nowatch: true });
+
+    } catch (error) {
+        messages.push(`\n   SPEC-UP-T: An error occurred - ${error.message}\n`);
+    }
+}
+
+// Export the updateXrefs and removeXref functions for use in other modules.
 module.exports = {
-    addAllXrefs,
-    removeXref
+    updateXrefs,
+    removeXref,
+    addXref
 }