Merge branch 'develop' into sidv/vitest

* develop: (28 commits)
  fix(docs): update link
  Revert "unify Jison tranformers"
  Update yarn.lock
  Revert "fix(test): No esm exports"
  fix(test): No esm exports
  fix(docs): `mmd` detection
  Hope this fails
  unify Jison tranformers
  Fix jest
  Remove `docs:build` from postbuild.
  Add verification log
  This should fail CI
  fix: imports in HTML
  Revert "Add diagramAPI to outfile"
  Add `type: module` to package.json
  chore(deps-dev): bump @types/lodash from 4.14.184 to 4.14.185
  Update integrations.md
  Add vitepress pluin
  Update mermaid version
  Fix ports
  ...

src/docs.mts

@@ -1,11 +1,10 @@
 /* eslint-disable no-console */
 
 /**
- * @file Transform documentation source files into files suitable for publishing
- *   and optionally copy the transformed files from the source directory to the
- *   directory used for the final, published documentation directory. The list
- *   of files transformed and copied to final documentation directory are logged
- *   to the console. If a file in the source directory has the same contents in
+ * @file Transform documentation source files into files suitable for publishing and optionally copy
+ *   the transformed files from the source directory to the directory used for the final, published
+ *   documentation directory. The list of files transformed and copied to final documentation
+ *   directory are logged to the console. If a file in the source directory has the same contents in
  *   the final directory, nothing is done (the final directory is up-to-date).
  * @example
  *   docs
@@ -24,12 +23,12 @@
  *   If the --git option is used, the command `git add docs` will be run after all transformations (and/or verifications) have completed successfully
  *   If not files were transformed, the git command is not run.
  *
- * @todo Ensure that the documentation source and final paths are correct by
- *   using process.cwd() to get their absolute paths. Ensures that the location
- *   of those 2 directories is not dependent on where this file resides.
+ * @todo Ensure that the documentation source and final paths are correct by using process.cwd() to
+ *   get their absolute paths. Ensures that the location of those 2 directories is not dependent on
+ *   where this file resides.
  *
- * @todo Write a test file for this. (Will need to be able to deal .mts file.
- *   Jest has trouble with it.)
+ * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
+ *   it.)
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { exec } from 'child_process';
@@ -68,14 +67,13 @@ const prettierConfig: prettier.Config = {
 let filesWereTransformed = false;
 
 /**
- * Given a source file name and path, return the documentation destination full
- * path and file name Create the destination path if it does not already exist.
+ * Given a source file name and path, return the documentation destination full path and file name
+ * Create the destination path if it does not already exist.
  *
  * @param {string} file - Name of the file (including full path)
- * @returns {string} Name of the file with the path changed from the source
- *   directory to final documentation directory
- * @todo Possible Improvement: combine with lint-staged to only copy files that
- *   have changed
+ * @returns {string} Name of the file with the path changed from the source directory to final
+ *   documentation directory
+ * @todo Possible Improvement: combine with lint-staged to only copy files that have changed
  */
 const changeToFinalDocDir = (file: string): string => {
   const newDir = file.replace(SOURCE_DOCS_DIR, FINAL_DOCS_DIR);
@@ -84,8 +82,8 @@ const changeToFinalDocDir = (file: string): string => {
 };
 
 /**
- * Log messages to the console showing if the transformed file copied to the
- * final documentation directory or still needs to be copied.
+ * Log messages to the console showing if the transformed file copied to the final documentation
+ * directory or still needs to be copied.
  *
  * @param {string} filename Name of the file that was transformed
  * @param {boolean} wasCopied Whether or not the file was copied
@@ -101,14 +99,13 @@ const logWasOrShouldBeTransformed = (filename: string, wasCopied: boolean) => {
 };
 
 /**
- * If the file contents were transformed, set the _filesWereTransformed_ flag to
- * true and copy the transformed contents to the final documentation directory
- * if the doCopy flag is true. Log messages to the console.
+ * If the file contents were transformed, set the _filesWereTransformed_ flag to true and copy the
+ * transformed contents to the final documentation directory if the doCopy flag is true. Log
+ * messages to the console.
  *
  * @param {string} filename Name of the file that will be verified
- * @param {boolean} [doCopy=false] Whether we should copy that
- *   transformedContents to the final documentation directory. Default is
- *   `false`. Default is `false`
+ * @param {boolean} [doCopy=false] Whether we should copy that transformedContents to the final
+ *   documentation directory. Default is `false`
  * @param {string} [transformedContent] New contents for the file
  */
 const copyTransformedContents = (filename: string, doCopy = false, transformedContent?: string) => {
@@ -133,15 +130,14 @@ const readSyncedUTF8file = (filename: string): string => {
 };
 
 /**
- * Transform a markdown file and write the transformed file to the directory for
- * published documentation
+ * Transform a markdown file and write the transformed file to the directory for published
+ * documentation
  *
- * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the
- *    docsify site (one place where the documentation is published), this will
- *    show the code used for the mermaid diagram
+ * 1. Add a `mermaid-example` block before every `mermaid` or `mmd` block On the docsify site (one
+ *    place where the documentation is published), this will show the code used for the mermaid
+ *    diagram
  * 2. Add the text that says the file is automatically generated
- * 3. Use prettier to format the file Verify that the file has been changed and
- *    write out the changes
+ * 3. Use prettier to format the file Verify that the file has been changed and write out the changes
  *
  * @param file {string} name of the file that will be verified
  */
@@ -149,12 +145,15 @@ const transformMarkdown = (file: string) => {
   const doc = readSyncedUTF8file(file);
   const ast: Root = remark.parse(doc);
   const out = flatmap(ast, (c: Code) => {
-    if (c.type !== 'code' || !c.lang?.startsWith('mermaid')) {
+    if (c.type !== 'code') {
       return [c];
     }
     if (c.lang === 'mermaid' || c.lang === 'mmd') {
       c.lang = 'mermaid-example';
     }
+    if (c.lang !== 'mermaid-example') {
+      return [c];
+    }
     return [c, Object.assign({}, c, { lang: 'mermaid' })];
   });
 
@@ -168,11 +167,11 @@ const transformMarkdown = (file: string) => {
 };
 
 /**
- * Transform an HTML file and write the transformed file to the directory for
- * published documentation
+ * Transform an HTML file and write the transformed file to the directory for published
+ * documentation
  *
- * - Add the text that says the file is automatically generated Verify that the
- *   file has been changed and write out the changes
+ * - Add the text that says the file is automatically generated Verify that the file has been changed
+ *   and write out the changes
  *
  * @param filename {string} name of the HTML file to transform
  */
@@ -204,6 +203,9 @@ const transformHtml = (filename: string) => {
 
 /** Main method (entry point) */
 (async () => {
+  if (verifyOnly) {
+    console.log('Verifying that all files are in sync with the source files');
+  }
   const sourceDirGlob = join('.', SOURCE_DOCS_DIR, '**');
   const includeFilesStartingWithDot = true;
 

src/docs/integrations.md

@@ -49,6 +49,8 @@ They also serve as proof of concept, for the variety of things that can be built
 
 ## CMS
 
+- [VitePress](https://vitepress.vuejs.org/)
+  - [Plugin for Mermaid.js](https://emersonbottero.github.io/vitepress-plugin-mermaid/)
 - [VuePress](https://vuepress.vuejs.org/)
   - [Plugin for Mermaid.js](https://github.com/eFrane/vuepress-plugin-mermaidjs)
 - [Grav CMS](https://getgrav.org/)

src/jison/lint.mts

@@ -0,0 +1,31 @@
+/* eslint-disable no-console */
+import { readFile } from 'fs/promises';
+import { globby } from 'globby';
+import { ESLint } from 'eslint';
+// @ts-ignore no typings
+import jison from 'jison';
+
+const linter = new ESLint({
+  overrideConfig: { rules: { 'no-console': 'error' }, parser: '@typescript-eslint/parser' },
+  useEslintrc: false,
+});
+
+const lint = async (file: string): Promise<boolean> => {
+  const jisonCode = await readFile(file, 'utf8');
+  // @ts-ignore no typings
+  const jsCode = new jison.Generator(jisonCode, { moduleType: 'amd' }).generate();
+  const [result] = await linter.lintText(jsCode);
+  if (result.errorCount > 0) {
+    console.error(`Linting failed for ${file}`);
+    console.error(result.messages);
+  }
+  return result.errorCount === 0;
+};
+
+(async () => {
+  const jisonFiles = await globby(['./src/**/*.jison'], { dot: true });
+  const lintResults = await Promise.all(jisonFiles.map(lint));
+  if (lintResults.some((result) => result === false)) {
+    process.exit(1);
+  }
+})();