spec-up-t 1.0.73 → 1.0.75

package/index.spec-up.js

@@ -0,0 +1,366 @@
+
+module.exports = function (options = {}) {
+
+  const {
+    fetchExternalSpecs,
+    validateReferences,
+    findExternalSpecByKey
+  } = require('./references.js');
+  const gulp = require('gulp');
+  const fs = require('fs-extra');
+  const path = require('path');
+  const findPkgDir = require('find-pkg-dir');
+  const modulePath = findPkgDir(__dirname);
+  let config = fs.readJsonSync('./specs.json');
+  let assets = fs.readJsonSync(modulePath + '/src/asset-map.json');
+  let externalReferences;
+  let references = [];
+  let definitions = [];
+
+  const katexRules = ['math_block', 'math_inline']
+  const replacerRegex = /\[\[\s*([^\s\[\]:]+):?\s*([^\]\n]+)?\]\]/img;
+  const replacerArgsRegex = /\s*,+\s*/;
+  const replacers = [
+    {
+      test: 'insert',
+      transform: function (path) {
+        if (!path) return '';
+        return fs.readFileSync(path, 'utf8');
+      }
+    }
+  ];
+
+  function applyReplacers(doc) {
+    return doc.replace(replacerRegex, function (match, type, args) {
+      let replacer = replacers.find(r => type.trim().match(r.test));
+      return replacer ? replacer.transform(...args.trim().split(replacerArgsRegex)) : match;
+    });
+  }
+
+  function normalizePath(path) {
+    return path.trim().replace(/\/$/g, '') + '/';
+  }
+
+  function renderRefGroup(type) {
+    let group = specGroups[type];
+    if (!group) return '';
+    let html = Object.keys(group).sort().reduce((html, name) => {
+      let ref = group[name];
+      return html += `
+        <dt id="ref:${name}">${name}</dt>
+        <dd>
+          <cite><a href="${ref.href}">${ref.title}</a></cite>. 
+          ${ref.authors.join('; ')}; ${ref.rawDate}. <span class="reference-status">Status: ${ref.status}</span>.
+        </dd>
+      `;
+    }, '<dl class="reference-list">')
+    return `\n${html}\n</dl>\n`;
+  }
+
+  function findKatexDist() {
+    const relpath = "node_modules/katex/dist";
+    const paths = [
+      path.join(process.cwd(), relpath),
+      path.join(__dirname, relpath),
+    ];
+    for (const abspath of paths) {
+      if (fs.existsSync(abspath)) {
+        return abspath
+      }
+    }
+    throw Error("katex distribution could not be located");
+  }
+
+  try {
+
+    var toc;
+    var specGroups = {};
+    const noticeTypes = {
+      note: 1,
+      issue: 1,
+      example: 1,
+      warning: 1,
+      todo: 1
+    };
+    const spaceRegex = /\s+/g;
+    const specNameRegex = /^spec$|^spec[-]*\w+$/i;
+    const terminologyRegex = /^def$|^ref$|^xref/i;
+    const specCorpus = fs.readJsonSync(modulePath + '/assets/compiled/refs.json');
+    const containers = require('markdown-it-container');
+    const md = require('markdown-it')({
+      html: true,
+      linkify: true,
+      typographer: true
+    })
+      .use(require('./src/markdown-it-extensions.js'), [
+        {
+          filter: type => type.match(terminologyRegex),
+          parse(token, type, primary) {
+            if (!primary) return;
+            if (type === 'def') {
+              definitions.push(token.info.args);
+              return token.info.args.reduce((acc, syn) => {
+                return `<span id="term:${syn.replace(spaceRegex, '-').toLowerCase()}">${acc}</span>`;
+              }, primary);
+            }
+            else if (type === 'xref') {
+              const url = findExternalSpecByKey(config, token.info.args[0]);
+              const term = token.info.args[1].replace(spaceRegex, '-').toLowerCase();
+              return `<a class="term-reference" data-local-href="#term:${token.info.args[0]}:${term}"
+                href="${url}#term:${term}">${token.info.args[1]}</a>`;
+            }
+            else {
+              references.push(primary);
+              return `<a class="term-reference" href="#term:${primary.replace(spaceRegex, '-').toLowerCase()}">${primary}</a>`;
+            }
+          }
+        },
+        {
+          filter: type => type.match(specNameRegex),
+          parse(token, type, name) {
+            if (name) {
+              let _name = name.replace(spaceRegex, '-').toUpperCase();
+              let spec = specCorpus[_name] ||
+                specCorpus[_name.toLowerCase()] ||
+                specCorpus[name.toLowerCase()] ||
+                specCorpus[name];
+              if (spec) {
+                spec._name = _name;
+                let group = specGroups[type] = specGroups[type] || {};
+                token.info.spec = group[_name] = spec;
+              }
+            }
+          },
+          render(token, type, name) {
+            if (name) {
+              let spec = token.info.spec;
+              if (spec) return `[<a class="spec-reference" href="#ref:${spec._name}">${spec._name}</a>]`;
+            }
+            else return renderRefGroup(type);
+          }
+        }
+      ])
+      .use(require('markdown-it-attrs'))
+      .use(require('markdown-it-chart').default)
+      .use(require('markdown-it-deflist'))
+      .use(require('markdown-it-references'))
+      .use(require('markdown-it-icons').default, 'font-awesome')
+      .use(require('markdown-it-ins'))
+      .use(require('markdown-it-mark'))
+      .use(require('markdown-it-textual-uml'))
+      .use(require('markdown-it-sub'))
+      .use(require('markdown-it-sup'))
+      .use(require('markdown-it-task-lists'))
+      .use(require('markdown-it-multimd-table'), {
+        multiline: true,
+        rowspan: true,
+        headerless: true
+      })
+      .use(containers, 'notice', {
+        validate: function (params) {
+          let matches = params.match(/(\w+)\s?(.*)?/);
+          return matches && noticeTypes[matches[1]];
+        },
+        render: function (tokens, idx) {
+          let matches = tokens[idx].info.match(/(\w+)\s?(.*)?/);
+          if (matches && tokens[idx].nesting === 1) {
+            let id;
+            let type = matches[1];
+            if (matches[2]) {
+              id = matches[2].trim().replace(/\s+/g, '-').toLowerCase();
+              if (noticeTitles[id]) id += '-' + noticeTitles[id]++;
+              else noticeTitles[id] = 1;
+            }
+            else id = type + '-' + noticeTypes[type]++;
+            return `<div id="${id}" class="notice ${type}"><a class="notice-link" href="#${id}">${type.toUpperCase()}</a>`;
+          }
+          else return '</div>\n';
+        }
+      })
+      .use(require('markdown-it-prism'))
+      .use(require('markdown-it-toc-and-anchor').default, {
+        tocClassName: 'toc',
+        tocFirstLevel: 2,
+        tocLastLevel: 4,
+        tocCallback: (_md, _tokens, html) => toc = html,
+        anchorLinkSymbol: '§',
+        anchorClassName: 'toc-anchor'
+      })
+      .use(require('@traptitech/markdown-it-katex'))
+
+    async function render(spec, assets) {
+      try {
+        noticeTitles = {};
+        specGroups = {};
+        console.log('Rendering: ' + spec.title);
+        return new Promise(async (resolve, reject) => {
+          Promise.all((spec.markdown_paths || ['spec.md']).map(_path => {
+            return fs.readFile(spec.spec_directory + _path, 'utf8').catch(e => reject(e))
+          })).then(async docs => {
+            const features = (({ source, logo }) => ({ source, logo }))(spec);
+            if (spec.external_specs && !externalReferences) {
+              externalReferences = await fetchExternalSpecs(spec);
+            }
+            let doc = docs.join("\n");
+            doc = applyReplacers(doc);
+            md[spec.katex ? "enable" : "disable"](katexRules);
+            const render = md.render(doc);
+            fs.writeFile(path.join(spec.destination, 'index.html'), `
+              <!DOCTYPE html>
+              <html lang="en">
+                <head>
+                  <meta charset="utf-8">
+                  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+                  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+      
+                  <title>${spec.title}</title>
+
+                  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@300;400&display=swap" rel="stylesheet">
+
+                  ${assets.head}
+                </head>
+                <body features="${Object.keys(features).join(' ')}">
+                  
+                  ${assets.svg}
+      
+                  <main>
+      
+                    <header id="header" class="panel-header">
+                      <span id="toc_toggle" panel-toggle="toc">
+                        <svg icon><use xlink:href="#svg-nested-list"></use></svg>
+                      </span>
+                      <a id="logo" href="${spec.logo_link ? spec.logo_link : '#_'}">
+                        <img src="${spec.logo}" />
+                      </a>
+                      <span issue-count animate panel-toggle="repo_issues">
+                        <svg icon><use xlink:href="#svg-github"></use></svg>
+                      </span>
+                    </header>
+      
+                    <article id="content">
+                      ${render}
+                    </article>    
+      
+                  </main>
+      
+                  <slide-panels id="slidepanels">
+                    <slide-panel id="repo_issues" options="right">
+                      <header class="panel-header">
+                        <span>
+                          <svg icon><use xlink:href="#svg-github"></use></svg>
+                          <span issue-count></span>
+                        </span>
+                        <span class="repo-issue-toggle" panel-toggle="repo_issues">✕</span>
+                      </header>
+                      <ul id="repo_issue_list"></ul>
+                    </slide-panel>
+      
+                    <slide-panel id="toc">
+                      <header class="panel-header">
+                        <span>Table of Contents</span>
+                        <span panel-toggle="toc">✕</span>
+                      </header>
+                      <div id="toc_list">
+                        ${toc}
+                      </div>
+                    </slide-panel>
+                    
+                  </slide-panels>
+                  <div style="display: none;">
+                    ${externalReferences}
+                  </div>
+                </body>
+                <script>window.specConfig = ${JSON.stringify(spec)}</script>
+                ${assets.body}
+              </html>
+            `, function (err, data) {
+              if (err) {
+                reject(err);
+              }
+              else {
+                resolve();
+              }
+            });
+            validateReferences(references, definitions, render);
+            references = [];
+            definitions = [];
+          });
+        });
+      }
+      catch (e) {
+        console.error(e);
+      }
+    }
+
+    config.specs.forEach(spec => {
+      spec.spec_directory = normalizePath(spec.spec_directory);
+      spec.destination = normalizePath(spec.output_path || spec.spec_directory);
+
+      fs.ensureDirSync(spec.destination);
+
+      let assetTags = {
+        svg: fs.readFileSync(modulePath + '/assets/icons.svg', 'utf8') || ''
+      };
+
+      let customAssets = (spec.assets || []).reduce((assets, asset) => {
+        let ext = asset.path.split('.').pop();
+        if (ext === 'css') {
+          assets.css += `<link href="${asset.path}" rel="stylesheet"/>`;
+        }
+        if (ext === 'js') {
+          assets.js[asset.inject || 'body'] += `<script src="${asset.path}" ${asset.module ? 'type="module"' : ''} ></script>`;
+        }
+        return assets;
+      }, {
+        css: '',
+        js: { head: '', body: '' }
+      });
+
+      if (options.dev) {
+        assetTags.head = assets.head.css.map(_path => `<link href="${_path}" rel="stylesheet"/>`).join('') +
+          customAssets.css +
+          assets.head.js.map(_path => `<script src="${_path}"></script>`).join('') +
+          customAssets.js.head;
+        assetTags.body = assets.body.js.map(_path => `<script src="${_path}" data-manual></script>`).join('') +
+          customAssets.js.body;
+      }
+      else {
+        assetTags.head = `
+          <style>${fs.readFileSync(modulePath + '/assets/compiled/head.css', 'utf8')}</style>
+          ${customAssets.css}
+          <script>${fs.readFileSync(modulePath + '/assets/compiled/head.js', 'utf8')}</script>
+          ${customAssets.js.head}
+        `;
+        assetTags.body = `<script>${fs.readFileSync(modulePath + '/assets/compiled/body.js', 'utf8')}</script>
+                          ${customAssets.js.body}`;
+      }
+
+      if (spec.katex) {
+        const katexDist = findKatexDist();
+        assetTags.body += `<script>/* katex */${fs.readFileSync(path.join(katexDist, 'katex.min.js'),
+          'utf8')}</script>`;
+        assetTags.body += `<style>/* katex */${fs.readFileSync(path.join(katexDist, 'katex.min.css'),
+          'utf8')}</style>`;
+
+        fs.copySync(path.join(katexDist, 'fonts'), path.join(spec.destination, 'fonts'));
+      }
+
+      if (!options.nowatch) {
+        gulp.watch(
+          [spec.spec_directory + '**/*', '!' + path.join(spec.destination, 'index.html')],
+          render.bind(null, spec, assetTags)
+        )
+      }
+
+      render(spec, assetTags).then(() => {
+        if (options.nowatch) process.exit(0)
+      }).catch(() => process.exit(1));
+
+    });
+
+  }
+  catch (e) {
+    console.error(e);
+  }
+
+}

package/package.json

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

@@ -1,5 +1,10 @@
 /**
- * @file This file creates a JavaScript file with the data for the xrefs. It fetches the latest commit hash of the term files from the GitHub API and stores the data in a JavaScript file that is included in the HTML output of the specification. The outputted JS file serves as a source for the JS code that will be included in the html file.
+ * @file This script is responsible for fetching the latest commit hash of term files from the GitHub API and generating both a JavaScript file and a JSON file containing the data for the cross-references (xrefs). 
+ * 
+ * The generated JavaScript file is included in the HTML output of the specification, serving as a data source for the JavaScript code embedded in the HTML file. 
+ * 
+ * Additionally, the data is written to a JSON file for further processing or usage. This ensures that the xref data is available in both JavaScript and JSON formats, providing flexibility for different use cases.
+ *
  * @author Kor Dwarshuis
  * @version 1.0.0
  * @since 2024-06-09
@@ -106,7 +111,7 @@ async function fetchFileContentFromCommit(GITHUB_API_TOKEN, owner, repo, commitH
     return null;
 }
 
-function updateXrefs(GITHUB_API_TOKEN) {
+function updateXrefs(GITHUB_API_TOKEN, skipExisting) {
     // 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) {
@@ -211,20 +216,19 @@ function updateXrefs(GITHUB_API_TOKEN) {
 
         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() {
+    async function fetchAllTermsInfoFromGithub(skipExisting) {
         for (let xref of allXrefs.xrefs) {
-            if (!xref.commitHash || !xref.content) {
+            if (!skipExisting || (!xref.commitHash || !xref.content)) {
                 const fetchedData = await fetchTermInfoFromGithub(GITHUB_API_TOKEN, xref);
                 if (fetchedData) {
                     xref.commitHash = fetchedData.commitHash;
                     xref.content = fetchedData.content;
                 }
-            }
-        }
+            }        }
     }
 
     // Fetch all term information, then write the results to JSON and JS files.
-    fetchAllTermsInfoFromGithub().then(() => {
+    fetchAllTermsInfoFromGithub(skipExisting).then(() => {
         const allXrefsStr = JSON.stringify(allXrefs, null, 2);
         fs.writeFileSync(outputPathJSON, allXrefsStr, 'utf8');
         const stringReadyForFileWrite = `const allXrefs = ${allXrefsStr};`;
@@ -238,96 +242,7 @@ function updateXrefs(GITHUB_API_TOKEN) {
     });
 }
 
-// Function to remove a specific xref from the JSON file, based on term and externalSpec.
-function removeXref(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}" not found.\n`);
-            return messages;
-        }
-
-        // 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');
-
-        messages.push(`\n   SPEC-UP-T: Entry with term "${term}" and externalSpec "${externalSpec}" removed.\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`);
-    }
-
-    // TODO: messages are not used at the moment, since they apparently are not returned to the calling script. Fix this.
-
-    return messages;
-}
-
-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 = {
-    updateXrefs,
-    removeXref,
-    addXref
+    updateXrefs
 }

package/src/prepare-tref.js

@@ -0,0 +1,7 @@
+function prepareTref(tref) {
+
+
+
+}
+
+module.export = { prepareTref };