markdownlint-cli2 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.12.0
+
+- Remove deprecated `markdownlint-cli2-config` entry point
+  - Use `markdownlint-cli2 --config ...` instead
+- Remove deprecated `markdownlint-cli2-fix` entry point
+  - Use `markdownlint-cli2 --fix ...` instead
+- Add `--help` and `--no-globs` parameters
+- Improve and document included JSON schemas
+- Update dependencies (including `markdownlint`)
+
 ## 0.11.0
 
 - Add `modulePaths` configuration option

package/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]
+Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--help]
 
 Glob expressions (from the globby library):
 - * matches any number of characters, but not /
@@ -83,8 +83,10 @@ Dot-only glob:
 - To lint every file in the current directory tree, the command "markdownlint-cli2 **" can be used instead
 
 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)
+- --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)
+- --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
 
 Configuration via:
 - .markdownlint-cli2.jsonc
@@ -126,17 +128,6 @@ below) to `true` (though it can still be overridden by a configuration file):
 markdownlint-cli2 --fix "**/*.md" "#node_modules"
 ```
 
-> **Deprecated**
->
-> The following command behaves similarly, defaulting the `fix` property to
-> `true`:
->
-> ```bash
-> markdownlint-cli2-fix "**/*.md" "#node_modules"
-> ```
->
-> Otherwise, `markdownlint-cli2-fix` behaves the same as `markdownlint-cli2`.
-
 In cases where it is not convenient to store a configuration file in the root
 of a project, the `--config` argument can be used to provide a path to any
 supported configuration file (except `package.json`):
@@ -150,24 +141,13 @@ above. For example, `.markdownlint.json` or `example.markdownlint-cli2.jsonc`.
 The specified configuration file will be loaded, parsed, and applied as a base
 configuration for the current directory - which will then be handled normally.
 
-> **Deprecated**
->
-> The following command behaves similarly, accepting a base configuration file
-> path as its first parameter:
->
-> ```bash
-> markdownlint-cli2-config "config/.markdownlint-cli2.jsonc" "**/*.md" "#node_modules"
-> ```
->
-> Otherwise, `markdownlint-cli2-config` behaves the same as `markdownlint-cli2`.
-
 ### Container Image
 
 A container image [`davidanson/markdownlint-cli2`][docker-hub-markdownlint-cli2]
 can also be used (e.g., as part of a CI pipeline):
 
 ```bash
-docker run -v $PWD:/workdir davidanson/markdownlint-cli2:v0.11.0 "**/*.md" "#node_modules"
+docker run -v $PWD:/workdir davidanson/markdownlint-cli2:v0.12.0 "**/*.md" "#node_modules"
 ```
 
 Notes:
@@ -184,18 +164,9 @@ Notes:
   - A custom working directory can be specified with Docker's `-w` flag:
 
     ```bash
-    docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:v0.11.0 "**/*.md" "#node_modules"
+    docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:v0.12.0 "**/*.md" "#node_modules"
     ```
 
-> **Deprecated**
->
-> To invoke the `markdownlint-cli2-config` or `markdownlint-cli2-fix` commands
-> instead, use Docker's `--entrypoint` flag:
->
-> ```bash
-> docker run -v $PWD:/workdir --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2:v0.11.0 "**/*.md" "#node_modules"
-> ```
-
 For convenience, the container image
 [`davidanson/markdownlint-cli2-rules`][docker-hub-markdownlint-cli2-rules]
 includes the latest versions of custom rules published to npm with the tag
@@ -254,9 +225,12 @@ of the rules within.
       4. `.markdownlint.yml`
       5. `.markdownlint.cjs`
       6. `.markdownlint.mjs`
-- The VS Code extension `vscode-markdownlint` includes a schema definition for
-  the `JSON(C)` configuration files described below. This adds auto-complete and
-  can make it easier to define proper structure.
+- The VS Code extension includes a [JSON Schema][json-schema] definition for the
+  `JSON(C)` configuration files described below. This adds auto-complete and can
+  make it easier to define proper structure.
+- See [markdownlint-cli2-config-schema.json][markdownlint-cli2-config-schema]
+  for that schema and [ValidatingConfiguration.md][validating-configuration] for
+  ways to use it to validate configuration files.
 
 ### `.markdownlint-cli2.jsonc`
 
@@ -286,6 +260,8 @@ of the rules within.
     command-line arguments
     - This setting can be used instead of (or in addition to) passing globs on
       the command-line and offers identical performance
+    - This setting is ignored when the `--no-globs` parameter is passed on the
+      command-line
     - This top-level setting is valid **only** in the directory from which
       `markdownlint-cli2` is run
   - `ignores`: `Array` of `String`s defining glob expressions to ignore when
@@ -420,7 +396,7 @@ reference to the `repos` list in that project's `.pre-commit-config.yaml` like:
 
 ```yaml
 - repo: https://github.com/DavidAnson/markdownlint-cli2
-  rev: v0.11.0
+  rev: v0.12.0
   hooks:
   - id: markdownlint-cli2
 ```
@@ -447,6 +423,7 @@ See [CHANGELOG.md][changelog].
 [homebrew]: https://brew.sh
 [html-comment]: https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started
 [json]: https://wikipedia.org/wiki/JSON
+[json-schema]: https://json-schema.org
 [jsonc]: https://code.visualstudio.com/Docs/languages/json#_json-with-comments
 [license-image]: https://img.shields.io/npm/l/markdownlint-cli2.svg
 [license-url]: https://opensource.org/licenses/MIT
@@ -455,26 +432,27 @@ See [CHANGELOG.md][changelog].
 [markdown-it-plugins]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
 [markdown-it-syntax-extensions]: https://github.com/markdown-it/markdown-it#syntax-extensions
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[markdownlint-config]: https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig
-[markdownlint-configuration]: https://github.com/DavidAnson/markdownlint/blob/main/README.md#configuration
-[markdownlint-custom-rules]: https://github.com/DavidAnson/markdownlint/blob/main/doc/CustomRules.md
-[markdownlint-options]: https://github.com/DavidAnson/markdownlint/blob/main/README.md#options
-[markdownlint-rules-aliases]: https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases
-[markdownlint-rules-tags]: https://github.com/DavidAnson/markdownlint/blob/main/README.md#tags
+[markdownlint-config]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#optionsconfig
+[markdownlint-configuration]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#configuration
+[markdownlint-custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/CustomRules.md
+[markdownlint-options]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#options
+[markdownlint-rules-aliases]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#rules--aliases
+[markdownlint-rules-tags]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#tags
 [markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
 [markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
 [markdownlint-cli2-action]: https://github.com/marketplace/actions/markdownlint-cli2-action
 [markdownlint-cli2-blog]: https://dlaa.me/blog/post/markdownlintcli2
-[markdownlint-cli2-formatter]: https://www.npmjs.com/search?q=keywords:markdownlint-cli2-formatter
 [markdownlint-cli2-cjs]: test/markdownlint-cli2-cjs/.markdownlint-cli2.cjs
+[markdownlint-cli2-config-schema]: schema/markdownlint-cli2-config-schema.json
+[markdownlint-cli2-formatter]: https://www.npmjs.com/search?q=keywords:markdownlint-cli2-formatter
 [markdownlint-cli2-jsonc]: test/markdownlint-cli2-jsonc-example/.markdownlint-cli2.jsonc
 [markdownlint-cli2-mjs]: test/markdownlint-cli2-mjs/.markdownlint-cli2.mjs
 [markdownlint-cli2-yaml]: test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml
 [markdownlint-cjs]: test/markdownlint-cjs/.markdownlint.cjs
-[markdownlint-jsonc]: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc
+[markdownlint-jsonc]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/schema/.markdownlint.jsonc
 [markdownlint-mjs]: test/markdownlint-mjs/.markdownlint.mjs
 [markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
-[markdownlint-yaml]: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+[markdownlint-yaml]: https://github.com/DavidAnson/markdownlint/blob/v0.32.1/schema/.markdownlint.yaml
 [nodejs]: https://nodejs.org/
 [nodejs-docker]: https://github.com/nodejs/docker-node
 [nodejs-docker-non-root]: https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md#non-root-user
@@ -490,6 +468,7 @@ See [CHANGELOG.md][changelog].
 [pre-commit-version]: https://pre-commit.com/#overriding-language-version
 [regexp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
 [regexp-constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp
+[validating-configuration]: schema/ValidatingConfiguration.md
 [vscode]: https://code.visualstudio.com/
 [vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
 [yaml]: https://wikipedia.org/wiki/YAML

package/markdownlint-cli2.js

@@ -26,7 +26,7 @@ const resolveAndRequire = require("./resolve-and-require");
 
 // Variables
 const packageName = "markdownlint-cli2";
-const packageVersion = "0.11.0";
+const packageVersion = "0.12.0";
 const libraryName = "markdownlint";
 const libraryVersion = markdownlintLibrary.getVersion();
 const dotOnlySubstitute = "*.{md,markdown}";
@@ -243,7 +243,7 @@ const processArgv = (argv) => {
 const showHelp = (logMessage) => {
   logMessage(`https://github.com/DavidAnson/markdownlint-cli2
 
-Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix]
+Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--help]
 
 Glob expressions (from the globby library):
 - * matches any number of characters, but not /
@@ -259,8 +259,10 @@ Dot-only glob:
 - To lint every file in the current directory tree, the command "markdownlint-cli2 **" can be used instead
 
 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)
+- --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)
+- --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
 
 Configuration via:
 - .markdownlint-cli2.jsonc
@@ -281,6 +283,7 @@ Cross-platform compatibility:
 The most compatible syntax for cross-platform support:
 $ markdownlint-cli2 "**/*.md" "#node_modules"`
   );
+  return 2;
 };
 
 // Get (creating if necessary) and process a directory's info object
@@ -893,9 +896,10 @@ const main = async (params) => {
     optionsOverride,
     fileContents,
     nonFileContents,
-    noGlobs,
-    noRequire,
-    name
+    noRequire
+  } = params;
+  let {
+    noGlobs
   } = params;
   const logMessage = params.logMessage || noop;
   const logError = params.logError || noop;
@@ -906,25 +910,36 @@ const main = async (params) => {
   const baseDir = posixPath(baseDirSystem);
   // Output banner
   logMessage(
-    `${name || packageName} v${packageVersion} (${libraryName} v${libraryVersion})`
+    `${packageName} v${packageVersion} (${libraryName} v${libraryVersion})`
   );
   // Merge and process args/argv
   let fixDefault = false;
   // eslint-disable-next-line unicorn/no-useless-undefined
   let configPath = undefined;
+  let shouldShowHelp = false;
   const argvFiltered = (argv || []).filter((arg) => {
     if (configPath === null) {
       configPath = arg;
       return false;
+      // eslint-disable-next-line unicorn/prefer-switch
     } else if (arg === "--config") {
       configPath = null;
       return false;
     } else if (arg === "--fix") {
       fixDefault = true;
       return false;
+    } else if (arg === "--help") {
+      shouldShowHelp = true;
+      return false;
+    } else if (arg === "--no-globs") {
+      noGlobs = true;
+      return false;
     }
     return true;
   });
+  if (shouldShowHelp) {
+    return showHelp(logMessage);
+  }
   // Read argv configuration file (if relevant and present)
   let optionsArgv = null;
   let relativeDir = null;
@@ -952,8 +967,7 @@ const main = async (params) => {
     ((globPatterns.length === 0) && !nonFileContents) ||
     (configPath === null)
   ) {
-    showHelp(logMessage);
-    return 2;
+    return showHelp(logMessage);
   }
   // Include any file overrides or non-file content
   const resolvedFileContents = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-cli2",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the `markdownlint` library",
   "author": {
     "name": "David Anson",
@@ -15,9 +15,7 @@
     "./markdownlint/helpers": "./export-markdownlint-helpers.js"
   },
   "bin": {
-    "markdownlint-cli2": "markdownlint-cli2.js",
-    "markdownlint-cli2-config": "markdownlint-cli2-config.js",
-    "markdownlint-cli2-fix": "markdownlint-cli2-fix.js"
+    "markdownlint-cli2": "markdownlint-cli2.js"
   },
   "homepage": "https://github.com/DavidAnson/markdownlint-cli2",
   "repository": {
@@ -29,7 +27,7 @@
   "scripts": {
     "build-docker-image": "VERSION=$(node -e \"process.stdout.write(require('./package.json').version)\") && docker build -t davidanson/markdownlint-cli2:v$VERSION -f docker/Dockerfile --label org.opencontainers.image.version=v$VERSION .",
     "build-docker-image-rules": "VERSION=$(node -e \"process.stdout.write(require('./package.json').version)\") && docker build -t davidanson/markdownlint-cli2-rules:v$VERSION -f docker/Dockerfile-rules --build-arg VERSION=v$VERSION --label org.opencontainers.image.version=v$VERSION .",
-    "ci": "npm-run-all --continue-on-error --parallel test-cover lint schema",
+    "ci": "npm-run-all --continue-on-error --parallel test-cover lint schema && git diff --exit-code",
     "lint": "eslint --max-warnings 0 --no-eslintrc --config .eslintrc.json .",
     "lint-dockerfile": "docker run --rm -i hadolint/hadolint:latest-alpine < docker/Dockerfile",
     "lint-watch": "git ls-files | entr npm run lint",
@@ -56,17 +54,16 @@
     "export-markdownlint-helpers.js",
     "LICENSE",
     "markdownlint-cli2.js",
-    "markdownlint-cli2-config.js",
-    "markdownlint-cli2-fix.js",
     "merge-options.js",
     "README.md",
     "resolve-and-require.js",
     "schema/markdownlint-cli2-config-schema.json",
-    "schema/markdownlint-config-schema.json"
+    "schema/markdownlint-config-schema.json",
+    "schema/ValidatingConfiguration.md"
   ],
   "dependencies": {
     "globby": "14.0.0",
-    "markdownlint": "0.32.1",
+    "markdownlint": "0.33.0",
     "markdownlint-cli2-formatter-default": "0.0.4",
     "micromatch": "4.0.5",
     "strip-json-comments": "5.0.1",
@@ -74,18 +71,18 @@
   },
   "devDependencies": {
     "@iktakahiro/markdown-it-katex": "4.0.1",
-    "ava": "5.3.1",
-    "c8": "8.0.1",
+    "ajv": "8.12.0",
+    "ava": "6.0.1",
+    "c8": "9.0.0",
     "cpy": "11.0.0",
     "cpy-cli": "5.0.0",
     "del": "7.1.0",
-    "eslint": "8.54.0",
-    "eslint-plugin-n": "16.3.1",
-    "eslint-plugin-unicorn": "49.0.0",
+    "eslint": "8.56.0",
+    "eslint-plugin-n": "16.6.2",
+    "eslint-plugin-unicorn": "50.0.1",
     "execa": "8.0.1",
-    "@hyperjump/json-schema": "1.6.5",
-    "markdown-it-emoji": "2.0.2",
-    "markdown-it-for-inline": "0.1.1",
+    "markdown-it-emoji": "3.0.0",
+    "markdown-it-for-inline": "2.0.1",
     "markdownlint-cli2-formatter-codequality": "0.0.4",
     "markdownlint-cli2-formatter-json": "0.0.7",
     "markdownlint-cli2-formatter-junit": "0.0.8",

package/schema/ValidatingConfiguration.md

@@ -0,0 +1,24 @@
+# Validating Configuration
+
+A [JSON Schema][json-schema] is provided to enable validating options objects:
+[`markdownlint-cli2-config-schema.json`][markdownlint-cli2-config-schema]
+
+Some editors automatically use a JSON Schema with files that reference it. For
+example, a `.markdownlint-cli2.jsonc` file with:
+
+```json
+"$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json"
+```
+
+A JSON Schema validator can be used to check configuration files like so:
+
+```bash
+npx ajv-cli validate -s ./markdownlint-cli2/schema/markdownlint-cli2-config-schema.json -r ./markdownlint-cli2/schema/markdownlint-config-schema.json -d "**/.markdownlint-cli2.{jsonc,yaml}" --strict=false
+```
+
+A similar process is documented for validating `markdownlint` configuration
+objects: [Validating Configuration][validating-configuration].
+
+[json-schema]: https://json-schema.org
+[markdownlint-cli2-config-schema]: markdownlint-cli2-config-schema.json
+[validating-configuration]: https://github.com/DavidAnson/markdownlint/blob/main/schema/ValidatingConfiguration.md

package/schema/markdownlint-cli2-config-schema.json

@@ -1,16 +1,17 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.12.0/schema/markdownlint-cli2-config-schema.json",
   "title": "markdownlint-cli2 configuration schema",
   "type": "object",
   "properties": {
     "$schema": {
-      "description": "JSON Schema URI (used by some editors)",
+      "description": "JSON Schema URI (expected by some editors)",
       "type": "string",
-      "default": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/main/schema/markdownlint-cli2-config-schema.json"
+      "default": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.12.0/schema/markdownlint-cli2-config-schema.json"
     },
     "config": {
       "description": "markdownlint-cli2 configuration schema",
-      "$ref": "./markdownlint-config-schema.json",
+      "$ref": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.33.0/schema/markdownlint-config-schema.json",
       "default": {}
     },
     "customRules": {