markdownlint 0.36.1 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.37.0
+
+- Convert module to ECMAScript (breaking change)
+  - <https://nodejs.org/docs/latest/api/esm.html>
+  - <https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c>
+- Convert module to named exports (breaking change)
+
 ## 0.36.1
 
 - Fix behavior of MD054

package/README.md

@@ -75,7 +75,7 @@ as well as directives, footnotes, and math syntax - all implemented by
 [markdownlint-problem-matcher]: https://github.com/xt0rted/markdownlint-problem-matcher
 [nodejs-extensions]: https://github.com/Lombiq/NodeJs-Extensions
 [rubygems-mdl]: https://rubygems.org/gems/mdl
-[sublimelinter]: https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint
+[sublimelinter]: https://github.com/jonlabelle/SublimeLinter-contrib-markdownlint
 [super-linter]: https://github.com/super-linter/super-linter
 [vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
 
@@ -312,42 +312,41 @@ alternate formats.
 
 ### Linting
 
-Standard asynchronous API:
+Asynchronous API via `import { lint } from "markdownlint/async"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
-function markdownlint(options, callback) { ... }
+function lint(options, callback) { ... }
 ```
 
-Synchronous API (for build scripts, etc.):
+Synchronous API via `import { lint } from "markdownlint/sync"`:
 
 ```javascript
 /**
- * Lint specified Markdown files synchronously.
+ * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {LintResults} Results object.
  */
-function markdownlint.sync(options) { ... }
+function lint(options) { ... }
 ```
 
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_fs_promises_api)):
+Promise API via `import { lint } from "markdownlint/promise"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {Promise<LintResults>} Results object.
  */
-function markdownlint(options) { ... }
+function lint(options) { ... }
 ```
 
 #### options
@@ -547,7 +546,7 @@ Type: `Object` implementing the [file system API][node-fs-api]
 
 In advanced scenarios, it may be desirable to bypass the default file system
 API. If a custom file system implementation is provided, `markdownlint` will use
-that instead of invoking `require("fs")`.
+that instead of using `node:fs`.
 
 Note: The only methods called are `readFile` and `readFileSync`.
 
@@ -669,14 +668,14 @@ By default, configuration files are parsed as JSON (and named
 `.markdownlint.json`). Custom parsers can be provided to handle other formats
 like JSONC, YAML, and TOML.
 
-Asynchronous API:
+Asynchronous API via `import { readConfig } from "markdownlint/async"`:
 
 ```javascript
 /**
  * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
- * @param {ConfigurationParser[] | ReadConfigCallback} parsers Parsing function.
+ * @param {ConfigurationParser[] | ReadConfigCallback} [parsers] Parsing function(s).
  * @param {Object} [fs] File system implementation.
  * @param {ReadConfigCallback} [callback] Callback (err, result) function.
  * @returns {void}
@@ -684,22 +683,21 @@ Asynchronous API:
 function readConfig(file, parsers, fs, callback) { ... }
 ```
 
-Synchronous API:
+Synchronous API via `import { readConfig } from "markdownlint/sync"`:
 
 ```javascript
 /**
- * Read specified configuration file synchronously.
+ * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
  * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
  */
-function readConfigSync(file, parsers, fs) { ... }
+function readConfig(file, parsers, fs) { ... }
 ```
 
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_promises_api)):
+Promise API via `import { readConfig } from "markdownlint/promise"`:
 
 ```javascript
 /**
@@ -751,7 +749,7 @@ Type: *Optional* `Object` implementing the [file system API][file-system-api]
 
 In advanced scenarios, it may be desirable to bypass the default file system
 API. If a custom file system implementation is provided, `markdownlint` will use
-that instead of invoking `require("fs")`.
+that instead of invoking `node:fs`.
 
 Note: The only methods called are `readFile`, `readFileSync`, `access`, and
 `accessSync`.
@@ -772,7 +770,8 @@ Configuration object.
 
 Rules that can be fixed automatically include a `fixInfo` property which is
 outlined in the [documentation for custom rules](doc/CustomRules.md#authoring).
-To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used:
+To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used via
+`import { applyFix, applyFixes } from "markdownlint"`:
 
 ```javascript
 /**
@@ -798,20 +797,44 @@ function applyFixes(input, errors) { ... }
 Invoking `applyFixes` with the results of a call to lint can be done like so:
 
 ```javascript
-const { "sync": markdownlintSync, applyFixes } = require("markdownlint");
+import { applyFixes } from "markdownlint";
+import { lint as lintSync } from "markdownlint/sync";
 
-function fixMarkdownlintViolations(content) {
-  const fixResults = markdownlintSync({ strings: { content } });
-  return applyFixes(content, fixResults.content);
-}
+const results = lintSync({ "strings": { "content": original } });
+const fixed = applyFixes(original, results.content);
 ```
 
+### Miscellaneous
+
+To get the [semantic version][semver] of the library, the `getVersion` method
+can be used:
+
+```javascript
+/**
+ * Gets the (semantic) version of the library.
+ *
+ * @returns {string} SemVer string.
+ */
+function getVersion() { ... }
+```
+
+Invoking `getVersion` is simple:
+
+```javascript
+import { getVersion } from "markdownlint";
+
+// Displays the library version
+console.log(getVersion());
+```
+
+[semver]: https://semver.org
+
 ## Usage
 
-Invoke `markdownlint` and use the `result` object's `toString` method:
+Invoke `lint` and use the `result` object's `toString` method:
 
 ```javascript
-const markdownlint = require("markdownlint");
+import { lint as lintAsync } from "markdownlint/async";
 
 const options = {
   "files": [ "good.md", "bad.md" ],
@@ -821,9 +844,9 @@ const options = {
   }
 };
 
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.log(result.toString());
+lintAsync(options, function callback(error, results) {
+  if (!error && results) {
+    console.log(results.toString());
   }
 });
 ```
@@ -841,21 +864,22 @@ bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [
 bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
 ```
 
-Or invoke `markdownlint.sync` for a synchronous call:
+Or as a synchronous call:
 
 ```javascript
-const result = markdownlint.sync(options);
-console.log(result.toString());
+import { lint as lintSync } from "markdownlint/sync";
+
+const results = lintSync(options);
+console.log(results.toString());
 ```
 
-To examine the `result` object directly:
+To examine the `result` object directly via a `Promise`-based call:
 
 ```javascript
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});
+import { lint as lintPromise } from "markdownlint/promise";
+
+const results = await lintPromise(options);
+console.dir(results, { "colors": true, "depth": null });
 ```
 
 Output:
@@ -897,80 +921,10 @@ Output:
 ```
 
 Integration with the [gulp](https://gulpjs.com/) build system is
-straightforward:
-
-```javascript
-const gulp = require("gulp");
-const through2 = require("through2");
-const markdownlint = require("markdownlint");
-
-gulp.task("markdownlint", function task() {
-  return gulp.src("*.md", { "read": false })
-    .pipe(through2.obj(function obj(file, enc, next) {
-      markdownlint(
-        { "files": [ file.relative ] },
-        function callback(err, result) {
-          const resultString = (result || "").toString();
-          if (resultString) {
-            console.log(resultString);
-          }
-          next(err, file);
-        });
-    }));
-});
-```
-
-Output:
-
-```text
-[00:00:00] Starting 'markdownlint'...
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
-[00:00:00] Finished 'markdownlint' after 10 ms
-```
+straightforward: [`gulpfile.cjs`](example/gulpfile.cjs).
 
 Integration with the [Grunt](https://gruntjs.com/) build system is similar:
-
-```javascript
-const markdownlint = require("markdownlint");
-
-module.exports = function wrapper(grunt) {
-  grunt.initConfig({
-    "markdownlint": {
-      "example": {
-        "src": [ "*.md" ]
-      }
-    }
-  });
-
-  grunt.registerMultiTask("markdownlint", function task() {
-    const done = this.async();
-    markdownlint(
-      { "files": this.filesSrc },
-      function callback(err, result) {
-        const resultString = err || ((result || "").toString());
-        if (resultString) {
-          grunt.fail.warn("\n" + resultString + "\n");
-        }
-        done(!err || !resultString);
-      });
-  });
-};
-```
-
-Output:
-
-```text
-Running "markdownlint:example" (markdownlint) task
-Warning:
-bad.md: 3: MD010/no-hard-tabs Hard tabs [Column: 17]
-bad.md: 1: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#bad.md"]
-bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [Context: "#This file fails      some rules."]
-bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
- Use --force to continue.
-```
+[`Gruntfile.cjs`](example/Gruntfile.cjs).
 
 ## Browser
 
@@ -982,11 +936,9 @@ Generate normal and minified scripts with:
 npm run build-demo
 ```
 
-Then reference `markdownlint` and `micromark` scripts:
+Then reference the `markdownlint-browser` script:
 
 ```html
-<script src="demo/micromark-browser.js"></script>
-<script src="demo/micromark-html-browser.js"></script>
 <script src="demo/markdownlint-browser.min.js"></script>
 ```
 
@@ -998,7 +950,8 @@ const options = {
     "content": "Some Markdown to lint."
   }
 };
-const results = window.markdownlint.sync(options).toString();
+
+const results = globalThis.markdownlint.lintSync(options).toString();
 ```
 
 ## Examples

package/doc/CustomRules.md

@@ -36,7 +36,7 @@ A simple rule implementation using the `micromark` parser to report a violation
 for any use of blockquotes might look like:
 
 ```javascript
-/** @type import("markdownlint").Rule */
+/** @type {import("markdownlint").Rule} */
 module.exports = {
   "names": [ "any-blockquote-micromark" ],
   "description": "Rule that reports an error for any blockquote",
@@ -61,7 +61,7 @@ module.exports = {
 That same rule implemented using the `markdown-it` parser might look like:
 
 ```javascript
-/** @type import("markdownlint").Rule */
+/** @type {import("markdownlint").Rule} */
 module.exports = {
   "names": [ "any-blockquote-markdown-it" ],
   "description": "Rule that reports an error for any blockquote",
@@ -160,8 +160,8 @@ implementation that is resolved when the rule completes. (The value passed to
 reported via the `onError` function just like for synchronous rules.
 
 **Note**: Asynchronous rules cannot be referenced in a synchronous calling
-context (i.e., `markdownlint.sync(...)`). Attempting to do so throws an
-exception.
+context (i.e., `import { lint } from "markdownlint/sync"`). Attempting to do so
+throws an exception.
 
 ## Examples
 
@@ -187,8 +187,8 @@ exception.
 [markdown-it-token]: https://markdown-it.github.io/markdown-it/#Token
 [markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
 [micromark]: https://github.com/micromark/micromark
-[micromark-token]: ../lib/markdownlint.d.ts
+[micromark-token]: ../lib/markdownlint.d.mts
 [rule-helpers]: https://www.npmjs.com/package/markdownlint-rule-helpers
 [options-custom-rules]: ../README.md#optionscustomrules
 [test-rules]: ../test/rules
-[tokens]: ../test/snapshots/markdownlint-test-custom-rules.js.md
+[tokens]: ../test/snapshots/markdownlint-test-custom-rules.mjs.md

package/helpers/README.md

@@ -22,8 +22,8 @@ be useful to custom rule authors and may avoid duplicating code.
 *None* - The entire body of code is tested to 100% coverage by the core
 `markdownlint` project, so there are no additional tests here.
 
-[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.36.1/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.37.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.36.1/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.37.0/doc/Rules.md

package/helpers/{helpers.js → helpers.cjs}

@@ -4,15 +4,24 @@
 
 const micromark = require("./micromark-helpers.cjs");
 
-const { newLineRe, nextLinesRe } = require("./shared.js");
+const { newLineRe, nextLinesRe } = require("./shared.cjs");
 
 module.exports.newLineRe = newLineRe;
 module.exports.nextLinesRe = nextLinesRe;
 
-/** @typedef {import("../lib/markdownlint.js").RuleOnError} RuleOnError */
-/** @typedef {import("../lib/markdownlint.js").RuleOnErrorFixInfo} RuleOnErrorFixInfo */
+// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
+/** @typedef {import("markdownlint").RuleOnError} RuleOnError */
+// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
+/** @typedef {import("markdownlint").RuleOnErrorFixInfo} RuleOnErrorFixInfo */
+// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
+/** @typedef {import("markdownlint").MicromarkToken} MicromarkToken */
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {import("micromark-extension-gfm-footnote", { with: { "resolution-mode": "import" } })} */
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} */
 
 // Regular expression for matching common front matter (YAML and TOML)
+// @ts-ignore
 module.exports.frontMatterRe =
   /((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m;
 
@@ -336,8 +345,8 @@ const positionLessThanOrEqual = (lineA, columnA, lineB, columnB) => (
 /**
  * Returns whether two ranges (or MicromarkTokens) overlap anywhere.
  *
- * @param {FileRange|import("../lib/markdownlint.js").MicromarkToken} rangeA Range A.
- * @param {FileRange|import("../lib/markdownlint.js").MicromarkToken} rangeB Range B.
+ * @param {FileRange|MicromarkToken} rangeA Range A.
+ * @param {FileRange|MicromarkToken} rangeB Range B.
  * @returns {boolean} True iff the two ranges overlap.
  */
 module.exports.hasOverlap = function hasOverlap(rangeA, rangeB) {
@@ -364,7 +373,7 @@ module.exports.frontMatterHasTitle =
 /**
  * Returns an object with information about reference links and images.
  *
- * @param {import("../helpers/micromark-helpers.cjs").Token[]} tokens Micromark tokens.
+ * @param {MicromarkToken[]} tokens Micromark tokens.
  * @returns {Object} Reference link/image data.
  */
 function getReferenceLinkImageData(tokens) {

package/helpers/micromark-helpers.cjs

@@ -2,10 +2,12 @@
 
 "use strict";
 
-const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.js");
+const { flatTokensSymbol, htmlFlowSymbol } = require("./shared.cjs");
 
-/** @typedef {import("markdownlint-micromark").TokenType} TokenType */
-/** @typedef {import("../lib/markdownlint.js").MicromarkToken} Token */
+// eslint-disable-next-line jsdoc/valid-types
+/** @typedef {import("micromark-util-types", { with: { "resolution-mode": "import" } }).TokenType} TokenType */
+// @ts-expect-error https://github.com/microsoft/TypeScript/issues/52529
+/** @typedef {import("markdownlint").MicromarkToken} Token */
 
 /**
  * Determines if a Micromark token is within an htmlFlow type.

package/helpers/package.json

@@ -2,9 +2,9 @@
   "name": "markdownlint-rule-helpers",
   "version": "0.27.0",
   "description": "A collection of markdownlint helper functions for custom rules",
-  "main": "./helpers.js",
+  "main": "./helpers.cjs",
   "exports": {
-    ".": "./helpers.js",
+    ".": "./helpers.cjs",
     "./micromark": "./micromark-helpers.cjs"
   },
   "author": "David Anson (https://dlaa.me/)",
@@ -19,9 +19,6 @@
   "engines": {
     "node": ">=18"
   },
-  "dependencies": {
-    "markdownlint-micromark": "0.1.2"
-  },
   "keywords": [
     "markdownlint",
     "markdownlint-rule"

package/lib/{cache.js → cache.mjs}

@@ -1,9 +1,7 @@
 // @ts-check
 
-"use strict";
-
-const helpers = require("../helpers");
-const { filterByTypes } = require("../helpers/micromark-helpers.cjs");
+import { getReferenceLinkImageData as helpersGetReferenceLinkImageData } from "../helpers/helpers.cjs";
+import { filterByTypes } from "../helpers/micromark-helpers.cjs";
 
 /** @type {Map<string, object>} */
 const map = new Map();
@@ -12,10 +10,10 @@ let params = undefined;
 /**
  * Initializes (resets) the cache.
  *
- * @param {import("./markdownlint").RuleParams} [p] Rule parameters object.
+ * @param {import("markdownlint").RuleParams} [p] Rule parameters object.
  * @returns {void}
  */
-function initialize(p) {
+export function initialize(p) {
   map.clear();
   params = p;
 }
@@ -39,11 +37,11 @@ function getCached(name, getValue) {
 /**
  * Filters a list of Micromark tokens by type and caches the result.
  *
- * @param {import("./markdownlint").MicromarkTokenType[]} types Types to allow.
+ * @param {import("markdownlint").MicromarkTokenType[]} types Types to allow.
  * @param {boolean} [htmlFlow] Whether to include htmlFlow content.
- * @returns {import("./markdownlint").MicromarkToken[]} Filtered tokens.
+ * @returns {import("markdownlint").MicromarkToken[]} Filtered tokens.
  */
-function filterByTypesCached(types, htmlFlow) {
+export function filterByTypesCached(types, htmlFlow) {
   return getCached(
     // eslint-disable-next-line prefer-rest-params
     JSON.stringify(arguments),
@@ -56,15 +54,9 @@ function filterByTypesCached(types, htmlFlow) {
  *
  * @returns {Object} Reference link and image data object.
  */
-function getReferenceLinkImageData() {
+export function getReferenceLinkImageData() {
   return getCached(
     getReferenceLinkImageData.name,
-    () => helpers.getReferenceLinkImageData(params.parsers.micromark.tokens)
+    () => helpersGetReferenceLinkImageData(params.parsers.micromark.tokens)
   );
 }
-
-module.exports = {
-  initialize,
-  filterByTypesCached,
-  getReferenceLinkImageData
-};