tools: notify user if format-md needs to be run

This will help enforce formatting of markdown files.

PR-URL: #40647
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

tools/lint-md/lint-md.mjs

@@ -29361,11 +29361,26 @@ const linter = unified()
 
 paths.forEach(async (path) => {
   const file = await read(path);
+  // We need to calculate `fileContents` before running `linter.process(files)`
+  // because `linter.process(files)` mutates `file` and returns it as `result`.
+  // So we won't be able to use `file` after that to see if its contents have
+  // changed as they will have been altered to the changed version.
+  const fileContents = file.toString();
   const result = await linter.process(file);
+  const isDifferent = fileContents !== result.toString();
   if (format) {
-    fs.writeFileSync(path, result.toString());
-  } else if (result.messages.length) {
-    process.exitCode = 1;
-    console.error(reporter(result));
+    if (isDifferent) {
+      fs.writeFileSync(path, result.toString());
+    }
+  } else {
+    if (isDifferent) {
+      process.exitCode = 1;
+      const cmd = process.platform === 'win32' ? 'vcbuild' : 'make';
+      console.error(`${path} is not formatted. Please run '${cmd} format-md'.`);
+    }
+    if (result.messages.length) {
+      process.exitCode = 1;
+      console.error(reporter(result));
+    }
   }
 });

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

@@ -28,11 +28,26 @@ const linter = unified()
 
 paths.forEach(async (path) => {
   const file = await read(path);
+  // We need to calculate `fileContents` before running `linter.process(files)`
+  // because `linter.process(files)` mutates `file` and returns it as `result`.
+  // So we won't be able to use `file` after that to see if its contents have
+  // changed as they will have been altered to the changed version.
+  const fileContents = file.toString();
   const result = await linter.process(file);
+  const isDifferent = fileContents !== result.toString();
   if (format) {
-    fs.writeFileSync(path, result.toString());
-  } else if (result.messages.length) {
-    process.exitCode = 1;
-    console.error(reporter(result));
+    if (isDifferent) {
+      fs.writeFileSync(path, result.toString());
+    }
+  } else {
+    if (isDifferent) {
+      process.exitCode = 1;
+      const cmd = process.platform === 'win32' ? 'vcbuild' : 'make';
+      console.error(`${path} is not formatted. Please run '${cmd} format-md'.`);
+    }
+    if (result.messages.length) {
+      process.exitCode = 1;
+      console.error(reporter(result));
+    }
   }
 });