Add markdownlint-cli2-formatter-template output formatter (fixes #426).

.github/dependabot.yml

@@ -53,3 +53,9 @@ updates:
       interval: "daily"
     target-branch: "next"
     versioning-strategy: "increase"
+  - package-ecosystem: "npm"
+    directory: "/formatter-template"
+    schedule:
+      interval: "daily"
+    target-branch: "next"
+    versioning-strategy: "increase"

.github/dictionary.txt

@@ -26,6 +26,7 @@ markdownlint-cli2-formatter-junit
 markdownlint-cli2-formatter-pretty
 markdownlint-cli2-formatter-sarif
 markdownlint-cli2-formatter-summarize
+markdownlint-cli2-formatter-template
 npm
 parsers
 POSIX

.github/workflows/ci.yml

@@ -65,8 +65,10 @@ jobs:
       run: cd formatter-sarif && npm pack
     - name: Package formatter-summarize
       run: cd formatter-summarize && npm pack
+    - name: Package formatter-template
+      run: cd formatter-template && npm pack
     - name: Install formatters globally
-      run: sudo npm install --global --no-package-lock --production ./formatter-default/*.tgz ./formatter-codequality/*.tgz ./formatter-json/*.tgz ./formatter-junit/*.tgz ./formatter-pretty/*.tgz ./formatter-sarif/*.tgz ./formatter-summarize/*.tgz
+      run: sudo npm install --global --no-package-lock --production ./formatter-default/*.tgz ./formatter-codequality/*.tgz ./formatter-json/*.tgz ./formatter-junit/*.tgz ./formatter-pretty/*.tgz ./formatter-sarif/*.tgz ./formatter-summarize/*.tgz ./formatter-template/*.tgz
     - name: Lint with formatters
       run: cp test/outputFormatters-npm/.markdownlint-cli2.jsonc . && markdownlint-cli2 CONTRIBUTING.md README.md
     - name: Uninstall markdownlint-cli2 globally

docker/Dockerfile

@@ -11,6 +11,7 @@ RUN cd formatter-junit && npm pack --pack-destination=..
 RUN cd formatter-pretty && npm pack --pack-destination=..
 RUN cd formatter-sarif && npm pack --pack-destination=..
 RUN cd formatter-summarize && npm pack --pack-destination=..
+RUN cd formatter-template && npm pack --pack-destination=..
 
 FROM node:lts-alpine
 COPY --from=build /pack/markdownlint-cli2-*.tgz /

formatter-template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) David Anson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

formatter-template/README.md

@@ -0,0 +1,92 @@
+# markdownlint-cli2-formatter-template
+
+> An output formatter for [`markdownlint-cli2`][markdownlint-cli2] that displays
+> results using a template.
+
+[![npm version][npm-image]][npm-url]
+[![License][license-image]][license-url]
+
+## Install
+
+```bash
+npm install markdownlint-cli2-formatter-template --save-dev
+```
+
+## Use
+
+This output formatter makes it easy to custom-format linting violations. To
+specify an output format, set the `template` parameter to a `string` with text
+and one or more tokens representing any of the following elements. The specified
+template will be applied once for each violation.
+
+These tokens are always defined:
+
+| Token             | Meaning               |
+|-------------------|-----------------------|
+| `fileName`        | File name             |
+| `lineNumber`      | Line number (1-based) |
+| `ruleName`        | Rule name (full)      |
+| `ruleDescription` | Rule description      |
+| `ruleInformation` | Informational URL     |
+
+These tokens are sometimes defined (depending on the rule/violation):
+
+| Token          | Meaning                 |
+|----------------|-------------------------|
+| `columnNumber` | Column number (1-based) |
+| `errorContext` | Context information     |
+| `errorDetail`  | Additional detail       |
+
+In the simplest case, tokens are specified with the syntax `${token}`. This is
+all that's needed for tokens that are always defined. To support scenarios where
+a token may not be defined, the syntaxes `${token:text if present}` and
+`${token!text if not present}` are also supported. This allows for templates to
+accomodate missing data. Only one level of token nesting is supported.
+
+A few examples demonstrate the concept:
+
+<!-- markdownlint-disable line-length -->
+
+| Template                                                                 | Output if defined | Output if not defined |
+|--------------------------------------------------------------------------|-------------------|-----------------------|
+| `Column=${columnNumber}`                                                 | `Column=10`       | `Column=`             |
+| `${columnNumber:Column=${columnNumber}}`                                 | `Column=10`       |                       |
+| `${columnNumber!No column number}`                                       |                   | `No column number`    |
+| `${columnNumber:Column=${columnNumber}}${columnNumber!No column number}` | `Column=10`       | `No column number`    |
+
+<!-- markdownlint-restore -->
+
+## Example
+
+To output in the [Azure Pipelines Task command LogIssue format][task-logissue],
+use something like the following `.markdownlint-cli2.jsonc`:
+
+```json
+{
+  "outputFormatters": [
+    [
+      "markdownlint-cli2-formatter-template",
+      {
+        "template": "##vso[task.logissue type=error;sourcepath=${fileName};linenumber=${lineNumber};${columnNumber:columnumber=${columnNumber};}code=${ruleName}]${ruleDescription}"
+      }
+    ]
+  ]
+}
+```
+
+Which produces output like:
+
+```text
+##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=3;columnumber=10;code=MD009/no-trailing-spaces]Trailing spaces
+##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=5;code=MD012/no-multiple-blanks]Multiple consecutive blank lines
+##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=6;code=MD025/single-title/single-h1]Multiple top-level headings in the same document
+##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=12;columnumber=4;code=MD019/no-multiple-space-atx]Multiple spaces after hash on atx style heading
+##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=14;columnumber=14;code=MD047/single-trailing-newline]Files should end with a single newline character
+```
+
+[license-image]: https://img.shields.io/npm/l/markdownlint-cli2-formatter-template.svg
+[license-url]: https://opensource.org/licenses/MIT
+[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
+[npm-image]: https://img.shields.io/npm/v/markdownlint-cli2-formatter-template.svg
+[npm-url]: https://www.npmjs.com/package/markdownlint-cli2-formatter-template
+[task-logissue]: https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops&tabs=bash#logissue-log-an-error-or-warning

formatter-template/markdownlint-cli2-formatter-template.js

@@ -0,0 +1,53 @@
+// @ts-check
+
+"use strict";
+
+// eslint-disable-next-line prefer-named-capture-group
+const tokenRe = /\$\{([^:!}]+)(?:([:!])([^{}]*\{[^{}]+\}[^{}]*|[^}]+))?\}/igu;
+
+// Output markdownlint-cli2 results using a template
+const outputFormatter = (options, params) => {
+  const { logError, results } = options;
+  const template = params?.template ||
+    // eslint-disable-next-line no-template-curly-in-string
+    "fileName=\"${fileName}\" lineNumber=${lineNumber} ${columnNumber:columnNumber=${columnNumber} }ruleName=${ruleName} ruleDescription=\"${ruleDescription}\" ruleInformation=${ruleInformation} errorContext=\"${errorContext}\" errorDetail=\"${errorDetail}\"";
+
+  for (const result of results) {
+    const tokenToResult = {
+      "fileName": result.fileName,
+      "lineNumber": result.lineNumber,
+      "columnNumber": result.errorRange?.[0],
+      "ruleName": result.ruleNames.join("/"),
+      "ruleDescription": result.ruleDescription,
+      "ruleInformation": result.ruleInformation,
+      "errorContext": result.errorContext,
+      "errorDetail": result.errorDetail
+    };
+
+    // eslint-disable-next-line unicorn/consistent-function-scoping
+    const replacer = (match, token, type, text) => {
+      const value = tokenToResult[token];
+      switch (type) {
+        case ":":
+        {
+          return (value === undefined) ? "" : text;
+        }
+        case "!":
+        {
+          return (value === undefined) ? text : "";
+        }
+        default:
+        {
+          return value ?? "";
+        }
+      }
+    };
+
+    const output = template.
+      replaceAll(tokenRe, replacer).
+      replaceAll(tokenRe, replacer);
+    logError(output);
+  }
+};
+
+module.exports = outputFormatter;

formatter-template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "markdownlint-cli2-formatter-template",
+  "version": "0.0.1",
+  "description": "An output formatter for markdownlint-cli2 that displays results using a template",
+  "author": {
+    "name": "David Anson",
+    "url": "https://dlaa.me/"
+  },
+  "license": "MIT",
+  "main": "markdownlint-cli2-formatter-template.js",
+  "homepage": "https://github.com/DavidAnson/markdownlint-cli2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavidAnson/markdownlint-cli2.git"
+  },
+  "bugs": "https://github.com/DavidAnson/markdownlint-cli2/issues",
+  "funding": "https://github.com/sponsors/DavidAnson",
+  "files": [
+    "markdownlint-cli2-formatter-template.js"
+  ],
+  "peerDependencies": {
+    "markdownlint-cli2": ">=0.0.4"
+  },
+  "keywords": [
+    "markdownlint-cli2-formatter"
+  ]
+}

package.json

@@ -103,6 +103,7 @@
     "markdownlint-cli2-formatter-pretty": "0.0.7",
     "markdownlint-cli2-formatter-sarif": "0.0.2",
     "markdownlint-cli2-formatter-summarize": "0.0.7",
+    "markdownlint-cli2-formatter-template": "0.0.1",
     "markdownlint-rule-extended-ascii": "0.1.0",
     "npm-run-all": "4.1.5"
   },

test/markdownlint-cli2-test.js

@@ -56,6 +56,7 @@ test("README files", (t) => {
     "./formatter-pretty/README.md",
     "./formatter-sarif/README.md",
     "./formatter-summarize/README.md",
+    "./formatter-template/README.md",
     "./schema/ValidatingConfiguration.md"
   ];
   return markdownlintCli2({
@@ -240,6 +241,7 @@ test("alternate file contents", (t) => {
     "./formatter-pretty/README.md",
     "./formatter-sarif/README.md",
     "./formatter-summarize/README.md",
+    "./formatter-template/README.md",
     "./test/all-ok/viewme.md",
     "./test/no-config/viewme.md",
     "./test/markdownlint-json/viewme.md",

test/outputFormatters-clean/.markdownlint-cli2.jsonc

@@ -5,6 +5,7 @@
     [ "../../formatter-json" ],
     [ "../../formatter-junit" ],
     [ "../../formatter-sarif" ],
-    [ "../../formatter-summarize" ]
+    [ "../../formatter-summarize" ],
+    [ "../../formatter-template" ]
   ]
 }

test/outputFormatters-npm/.markdownlint-cli2.jsonc

@@ -6,6 +6,7 @@
     [ "markdownlint-cli2-formatter-junit" ],
     [ "markdownlint-cli2-formatter-pretty" ],
     [ "markdownlint-cli2-formatter-sarif" ],
-    [ "markdownlint-cli2-formatter-summarize", { "byFile": true } ]
+    [ "markdownlint-cli2-formatter-summarize", { "byFile": true } ],
+    [ "markdownlint-cli2-formatter-template" ]
   ]
 }

test/outputFormatters-params/.markdownlint-cli2.jsonc

@@ -3,6 +3,8 @@
     [ "../../formatter-codequality", { "name": "custom-name-codequality.json" } ],
     [ "../../formatter-json", { "name": "custom-name-results.json", "spaces": 1 } ],
     [ "../../formatter-junit", { "name": "custom-name-junit.xml" } ],
-    [ "../../formatter-sarif", { "name": "custom-name-sarif.sarif" } ]
+    [ "../../formatter-sarif", { "name": "custom-name-sarif.sarif" } ],
+    [ "../../formatter-template", { "template": "##vso[task.logissue type=error;sourcepath=${fileName};linenumber=${lineNumber};${columnNumber:columnumber=${columnNumber};}code=${ruleName}]${ruleDescription}" } ],
+    [ "../../formatter-template", { "template": "#Undefined=${undefined}#Column=${columnNumber}#${columnNumber:Column=${columnNumber}}#${columnNumber!No column number}#${columnNumber:Column=${columnNumber}}${columnNumber!No column number}#" } ]
   ]
 }

test/outputFormatters/.markdownlint-cli2.jsonc

@@ -4,6 +4,7 @@
     [ "../../formatter-codequality" ],
     [ "../../formatter-json" ],
     [ "../../formatter-junit" ],
-    [ "../../formatter-sarif" ]
+    [ "../../formatter-sarif" ],
+    [ "../../formatter-template" ]
   ]
 }