tools: implement markdown formatting

Markdown formatter is now available via `mark format-md` (or
`vcbuild format-md` on Windows).

Author: Trott

Makefile

@@ -1253,6 +1253,13 @@ tools/.mdlintstamp: $(LINT_MD_FILES)
 # Lints the markdown documents maintained by us in the codebase.
 lint-md: lint-js-doc | tools/.mdlintstamp
 
+format-lint-md = tools/lint-md/lint-md.mjs --format $(LINT_MD_FILES)
+.PHONY: format-md
+# Formats the markdown documents maintained by us in the codebase.
+format-md:
+	@$(call available-node,$(run-lint-md))
+
+
 
 LINT_JS_TARGETS = .eslintrc.js benchmark doc lib test tools
 

tools/lint-md/lint-md.mjs

@@ -1,4 +1,5 @@
-import fs from 'fs';
+import * as fs from 'fs';
+import fs__default from 'fs';
 import path$1 from 'path';
 import { fileURLToPath, pathToFileURL, URL as URL$1 } from 'url';
 import process$1 from 'process';
@@ -19485,7 +19486,7 @@ function validateLinks(tree, vfile) {
   for (const node of getLinksRecursively(tree)) {
     if (node.url[0] !== "#") {
       const targetURL = new URL(node.url, currentFileURL);
-      if (targetURL.protocol === "file:" && !fs.existsSync(targetURL)) {
+      if (targetURL.protocol === "file:" && !fs__default.existsSync(targetURL)) {
         vfile.message("Broken link", node);
       } else if (targetURL.pathname === currentFileURL.pathname) {
         const expected = node.url.includes("#")
@@ -28313,7 +28314,7 @@ function toVFile(options) {
  */
 function readSync(description, options) {
   const file = toVFile(description);
-  file.value = fs.readFileSync(path$1.resolve(file.cwd, file.path), options);
+  file.value = fs__default.readFileSync(path$1.resolve(file.cwd, file.path), options);
   return file
 }
 
@@ -28326,7 +28327,7 @@ function readSync(description, options) {
  */
 function writeSync(description, options) {
   const file = toVFile(description);
-  fs.writeFileSync(path$1.resolve(file.cwd, file.path), file.value || '', options);
+  fs__default.writeFileSync(path$1.resolve(file.cwd, file.path), file.value || '', options);
   return file
 }
 
@@ -28381,7 +28382,7 @@ const read =
           return reject(error)
         }
 
-        fs.readFile(fp, options, done);
+        fs__default.readFile(fp, options, done);
 
         /**
          * @param {Error} error
@@ -28451,7 +28452,7 @@ const write =
           return reject(error)
         }
 
-        fs.writeFile(fp, file.value || '', options, done);
+        fs__default.writeFile(fp, file.value || '', options, done);
 
         /**
          * @param {Error} error
@@ -28936,7 +28937,7 @@ function reporter(files, options = {}) {
     files = [files];
   }
 
-  return format(transform(files, options), one, options)
+  return format$1(transform(files, options), one, options)
 }
 
 /**
@@ -29013,7 +29014,7 @@ function transform(files, options) {
  * @param {Options} options
  */
 // eslint-disable-next-line complexity
-function format(map, one, options) {
+function format$1(map, one, options) {
   /** @type {boolean} */
   const enabled =
     options.color === undefined || options.color === null
@@ -29155,6 +29156,18 @@ function size(value) {
 
 const paths = process.argv.slice(2);
 
+if (!paths.length) {
+  console.error('Usage: lint-md.mjs <path> [<path> ...]');
+  process.exit(1);
+}
+
+let format = false;
+
+if (paths[0] === '--format') {
+  paths.shift();
+  format = true;
+}
+
 const linter = unified()
   .use(remarkParse)
   .use(remarkGfm)
@@ -29164,9 +29177,10 @@ const linter = unified()
 paths.forEach(async (path) => {
   const file = await read(path);
   const result = await linter.process(file);
-  if (result.messages.length) {
+  if (format) {
+    fs.writeFileSync(path, String(result));
+  } else if (result.messages.length) {
     process.exitCode = 1;
     console.error(reporter(result));
   }
-  // TODO: allow reformatting by writing `String(result)` to the input file
 });

tools/lint-md/lint-md.src.mjs

@@ -1,3 +1,5 @@
+import * as fs from 'fs';
+
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
@@ -8,6 +10,18 @@ import { reporter } from 'vfile-reporter';
 
 const paths = process.argv.slice(2);
 
+if (!paths.length) {
+  console.error('Usage: lint-md.mjs <path> [<path> ...]');
+  process.exit(1);
+}
+
+let format = false;
+
+if (paths[0] === '--format') {
+  paths.shift();
+  format = true;
+}
+
 const linter = unified()
   .use(remarkParse)
   .use(gfm)
@@ -17,9 +31,10 @@ const linter = unified()
 paths.forEach(async (path) => {
   const file = await read(path);
   const result = await linter.process(file);
-  if (result.messages.length) {
+  if (format) {
+    fs.writeFileSync(path, String(result));
+  } else if (result.messages.length) {
     process.exitCode = 1;
     console.error(reporter(result));
   }
-  // TODO: allow reformatting by writing `String(result)` to the input file
 });

vcbuild.bat

@@ -726,6 +726,20 @@ for /D %%D IN (doc\*) do (
 ENDLOCAL
 goto exit
 
+:format-md
+if not defined lint_md goto exit
+echo Running Markdown formatter on docs...
+SETLOCAL ENABLEDELAYEDEXPANSION
+set lint_md_files=
+for /D %%D IN (doc\*) do (
+  for %%F IN (%%D\*.md) do (
+    set "lint_md_files="%%F" !lint_md_files!"
+  )
+)
+%node_exe% tools\lint-md\lint-md.mjs --format %lint_md_files%
+ENDLOCAL
+goto exit
+
 :create-msvs-files-failed
 echo Failed to create vc project files.
 del .used_configure_flags