tools: implement markdown formatting

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

PR-URL: #40181
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>

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
 
+run-format-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-format-md))
+
+
 
 LINT_JS_TARGETS = .eslintrc.js benchmark doc lib test tools
 

tools/lint-md/lint-md.mjs

@@ -28936,7 +28936,7 @@ function reporter(files, options = {}) {
     files = [files];
   }
 
-  return format(transform(files, options), one, options)
+  return format$1(transform(files, options), one, options)
 }
 
 /**
@@ -29013,7 +29013,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 +29155,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 +29176,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, result.toString());
+  } 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 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, result.toString());
+  } 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