Add --format command-line parameter to support editors that invoke tools to format via stdin/stdout (fixes #603).

Author: DavidAnson

README.md

@@ -67,7 +67,7 @@ As a [GitHub Action][github-action] via
 markdownlint-cli2 vX.Y.Z (markdownlint vX.Y.Z)
 https://github.com/DavidAnson/markdownlint-cli2
 
-Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--help] [--no-globs]
+Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--format] [--help] [--no-globs]
 
 Glob expressions (from the globby library):
 - * matches any number of characters, but not /
@@ -86,6 +86,7 @@ Dot-only glob:
 Optional parameters:
 - --config    specifies the path to a configuration file to define the base configuration
 - --fix       updates files to resolve fixable issues (can be overridden in configuration)
+- --format    reads standard input (stdin), applies fixes, writes standard output (stdout)
 - --help      writes this message to the console and exits without doing anything else
 - --no-globs  ignores the "globs" property if present in the top-level options object
 
@@ -213,6 +214,17 @@ parameter below.
 - `1`: Linting was successful and there were errors (and possibly warnings)
 - `2`: Linting was not successful due to a problem or failure
 
+### Formatting
+
+Some editors implement document formatting by invoking an external program,
+passing the text of the current document on standard input (`stdin`), and
+reading the formatted result from standard output (`stdout`). This scenario is
+supported by the `--format` command-line parameter. When `--format` is set:
+
+- Globs and other input sources are ignored
+- The `--fix` parameter is implicitly set
+- The exit code `1` is not used
+
 ## Rule List
 
 - See the [Rules / Aliases][markdownlint-rules-aliases] and
@@ -433,10 +445,6 @@ parameter below.
 - The `INI` config format, `.markdownlintrc`, and `.markdownlintignore` are not
   supported.
 
-### `vscode-markdownlint`
-
-- `.markdownlintignore` is not supported.
-
 ## pre-commit
 
 To run `markdownlint-cli2` as part of a [pre-commit][pre-commit] workflow, add a

markdownlint-cli2.mjs

@@ -229,7 +229,7 @@ const showHelp = (/** @type {Logger} */ logMessage, /** @type {boolean} */ showB
   }
   logMessage(`https://github.com/DavidAnson/markdownlint-cli2
 
-Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--help] [--no-globs]
+Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--format] [--help] [--no-globs]
 
 Glob expressions (from the globby library):
 - * matches any number of characters, but not /
@@ -248,6 +248,7 @@ Dot-only glob:
 Optional parameters:
 - --config    specifies the path to a configuration file to define the base configuration
 - --fix       updates files to resolve fixable issues (can be overridden in configuration)
+- --format    reads standard input (stdin), applies fixes, writes standard output (stdout)
 - --help      writes this message to the console and exits without doing anything else
 - --no-globs  ignores the "globs" property if present in the top-level options object
 
@@ -734,7 +735,7 @@ const createDirInfos = async (
 };
 
 // Lint files in groups by shared configuration
-const lintFiles = (/** @type {FsLike} */ fs, /** @type {DirInfo[]} */ dirInfos, /** @type {Record<string, string>} */ fileContents) => {
+const lintFiles = (/** @type {FsLike} */ fs, /** @type {DirInfo[]} */ dirInfos, /** @type {Record<string, string>} */ fileContents, /** @type {FormattingContext} */ formattingContext) => {
   const tasks = [];
   // For each dirInfo
   for (const dirInfo of dirInfos) {
@@ -790,8 +791,16 @@ const lintFiles = (/** @type {FsLike} */ fs, /** @type {DirInfo[]} */ dirInfos,
     };
     // Invoke markdownlint
     let task = lint(options);
-    // For any fixable errors, read file, apply fixes, and write it back
-    if (markdownlintOptions.fix) {
+    if (formattingContext.formatting) {
+      // Apply fixes to stdin input
+      task = task.then((results) => {
+        const [ [ id, original ] ] = Object.entries(filteredStrings);
+        const errorInfos = results[id];
+        formattingContext.formatted = applyFixes(original, errorInfos);
+        return {};
+      });
+    } else if (markdownlintOptions.fix) {
+      // For any fixable errors, read file, apply fixes, write it back, and re-lint
       task = task.then((results) => {
         options.files = [];
         const subTasks = [];
@@ -912,6 +921,8 @@ export const main = async (/** @type {Parameters} */ params) => {
     (directory && pathDefault.resolve(directory)) ||
     process.cwd();
   const baseDir = posixPath(baseDirSystem);
+  /** @type {FormattingContext} */
+  const formattingContext = {};
   // Merge and process args/argv
   let fixDefault = false;
   /** @type {undefined | null | string} */
@@ -934,6 +945,9 @@ export const main = async (/** @type {Parameters} */ params) => {
       configPath = null;
     } else if (arg === "--fix") {
       fixDefault = true;
+    } else if (arg === "--format") {
+      formattingContext.formatting = true;
+      useStdin = true;
     } else if (arg === "--help") {
       shouldShowHelp = true;
     } else if (arg === "--no-globs") {
@@ -972,7 +986,7 @@ export const main = async (/** @type {Parameters} */ params) => {
       Boolean(noImport)
     );
   } finally {
-    if (!baseOptions?.baseMarkdownlintOptions.noBanner) {
+    if (!baseOptions?.baseMarkdownlintOptions.noBanner && !formattingContext.formatting) {
       logMessage(bannerMessage);
     }
   }
@@ -1007,7 +1021,7 @@ export const main = async (/** @type {Parameters} */ params) => {
     Object.keys(nonFileContents || {})
   );
   // Output finding status
-  const showProgress = !baseMarkdownlintOptions.noProgress;
+  const showProgress = !baseMarkdownlintOptions.noProgress && !formattingContext.formatting;
   if (showProgress) {
     logMessage(`Finding: ${globPatterns.join(" ")}`);
   }
@@ -1046,29 +1060,33 @@ export const main = async (/** @type {Parameters} */ params) => {
     logMessage(`Linting: ${fileCount} file(s)`);
   }
   // Lint files
-  const lintResults = await lintFiles(fs, dirInfos, resolvedFileContents);
+  const lintResults = await lintFiles(fs, dirInfos, resolvedFileContents, formattingContext);
   // Output summary
   const results = createResults(baseDir, lintResults);
   if (showProgress) {
     logMessage(`Summary: ${results.length} error(s)`);
   }
-  const outputFormatters =
-    (optionsOverride && optionsOverride.outputFormatters) ||
-    baseMarkdownlintOptions.outputFormatters;
-  const modulePaths = resolveModulePaths(
-    baseDir,
-    baseMarkdownlintOptions.modulePaths || []
-  );
-  await outputResults(
-    baseDir,
-    relativeDir,
-    results,
-    outputFormatters,
-    modulePaths,
-    logMessage,
-    logError,
-    Boolean(noImport)
-  );
+  if (formattingContext.formatting) {
+    console.log(formattingContext.formatted);
+  } else {
+    const outputFormatters =
+      (optionsOverride && optionsOverride.outputFormatters) ||
+      baseMarkdownlintOptions.outputFormatters;
+    const modulePaths = resolveModulePaths(
+      baseDir,
+      baseMarkdownlintOptions.modulePaths || []
+    );
+    await outputResults(
+      baseDir,
+      relativeDir,
+      results,
+      outputFormatters,
+      modulePaths,
+      logMessage,
+      logError,
+      Boolean(noImport)
+    );
+  }
   // Return result
   const errorsPresent = lintResults.flatMap(
     (lintResult) => Object.values(lintResult).flatMap(
@@ -1141,6 +1159,12 @@ export const main = async (/** @type {Parameters} */ params) => {
 
 /** @typedef {import("markdownlint").LintError & LintContext} LintResult */
 
+/**
+ * @typedef FormattingContext
+ * @property {boolean} [formatting] True iff formatting.
+ * @property {string} [formatted] Formatted content.
+ */
+
 /**
  * @callback Logger
  * @param {string} msg Message.