markdownlint-cli2 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.22.0
+
+- Make `--config` parameter more flexible
+- Support TOML with `--config` parameter
+- Add `--configPointer` parameter
+- Update dependencies
+
+## 0.21.0
+
+- Refactor options/configuration file loading
+- Update dependencies
+
 ## 0.20.0
 
 - Update dependencies

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] [--format] [--help] [--no-globs]
+Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--configPointer pointer] [--fix] [--format] [--help] [--no-globs]
 
 Glob expressions (from the globby library):
 - * matches any number of characters, but not /
@@ -84,11 +84,12 @@ 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)
-- --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
+- --config        specifies the path to a configuration file to define the base configuration
+- --configPointer specifies a JSON Pointer to a configuration object within the --config file
+- --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
 
 Configuration via:
 - .markdownlint-cli2.jsonc
@@ -97,7 +98,6 @@ Configuration via:
 - .markdownlint.jsonc or .markdownlint.json
 - .markdownlint.yaml or .markdownlint.yml
 - .markdownlint.cjs or .markdownlint.mjs
-- package.json
 
 Cross-platform compatibility:
 - UNIX and Windows shells expand globs according to different rules; quoting arguments is recommended
@@ -133,24 +133,74 @@ markdownlint-cli2 --fix "**/*.md" "#node_modules"
 
 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`):
+supported configuration file/format:
 
 ```bash
 markdownlint-cli2 --config "config/.markdownlint-cli2.jsonc" "**/*.md" "#node_modules"
 ```
 
-The configuration file name must be (or end with) one of the supported names
+The configuration file name should be (or end with) one of the supported names
 above. For example, `.markdownlint.json` or `example.markdownlint-cli2.jsonc`.
-The specified configuration file will be loaded, parsed, and applied as a base
+Alternatively, the configuration file name should have a supported extension
+like `.jsonc`, `.yaml`, `.mjs`, or `.toml` and its kind (see below) will be
+inferred. The configuration file will be loaded, parsed, and applied as a base
 configuration for the current directory - which will then be handled normally.
 
+The `--configPointer` argument allows the use of [JSON Pointer][json-pointer]
+syntax to identify a sub-object within the configuration file specified by
+`--config` (see above). This argument can be used with any configuration file
+type and makes it possible to nest configuration data within another file like
+`package.json` or `pyproject.toml` (e.g., via `/key` or `/key/subkey`).
+
+For example, a `package.json` file like this:
+
+```json
+{
+  "...": "...",
+  "markdownlint-cli2": {
+    "config": {
+      "no-multiple-blanks": false
+    },
+    "noProgress": true
+  }
+}
+```
+
+Could be used like this:
+
+```bash
+markdownlint-cli2 --config package.json --configPointer /markdownlint-cli2 "*.md"
+```
+
+And a `pyproject.toml` file like this:
+
+```toml
+[project]
+# ...
+
+[tool.markdownlint-cli2]
+noProgress = true
+
+[tool.markdownlint-cli2.config]
+no-multiple-blanks = false
+```
+
+Could be used like this:
+
+```bash
+markdownlint-cli2 --config pyproject.toml --configPointer /tool/markdownlint-cli2 "*.md"
+```
+
+**Note**: The [TOML][toml] format is supported by `--config`, `--configPointer`,
+and the `extends` configuration property, but *not* for per-directory overrides.
+
 ### 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.20.0 "**/*.md" "#node_modules"
+docker run -v $PWD:/workdir davidanson/markdownlint-cli2:v0.22.0 "**/*.md" "#node_modules"
 ```
 
 Notes:
@@ -167,7 +217,7 @@ 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.20.0 "**/*.md" "#node_modules"
+    docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:v0.22.0 "**/*.md" "#node_modules"
     ```
 
 For convenience, the container image
@@ -256,7 +306,6 @@ supported by the `--format` command-line parameter. When `--format` is set:
       2. `.markdownlint-cli2.yaml`
       3. `.markdownlint-cli2.cjs`
       4. `.markdownlint-cli2.mjs`
-      5. `package.json` (only supported in the current directory)
   - Configuration files like `.markdownlint.*` allow control over only the
     `markdownlint` `config` object and tend to be supported more broadly (such
     as by `markdownlint-cli`).
@@ -268,6 +317,8 @@ supported by the `--format` command-line parameter. When `--format` is set:
       4. `.markdownlint.yml`
       5. `.markdownlint.cjs`
       6. `.markdownlint.mjs`
+  - Both configuration file types can appear in any directory and will override
+    configuration defined in the project root or any directories in between.
 - 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.
@@ -282,10 +333,10 @@ supported by the `--format` command-line parameter. When `--format` is set:
 - Valid properties are:
   - `config`: [`markdownlint` `config` object][markdownlint-config] to configure
     rules for this part of the directory tree
-    - If a `.markdownlint.{jsonc,json,yaml,yml,js}` file (see below) is present
-      in the same directory, it overrides the value of this property
+    - If a `.markdownlint.{jsonc,json,yaml,yml,cjs,mjs}` file (see below) is
+      present in the same directory, it overrides the value of this property
     - If the `config` object contains an `extends` property, it will be resolved
-      the same as `.markdownlint.{jsonc,json,yaml,yml,js}` (see below)
+      the same as `.markdownlint.{jsonc,json,yaml,yml,cjs,mjs}` (see below)
   - `customRules`: `Array` of `String`s (or `Array`s of `String`s) of module
     names/paths of [custom rules][markdownlint-custom-rules] to load and use
     when linting
@@ -301,12 +352,13 @@ supported by the `--format` command-line parameter. When `--format` is set:
     - For example: `(^---\s*$[^]*?^---\s*$)(\r\n|\r|\n|$)`
   - `gitignore`: `Boolean` or `String` value to automatically ignore files
     referenced by `.gitignore` (or similar) when linting
-    - When the value `true` is specified, all `.gitignore` files in the tree are
-      imported (default `git` behavior)
+    - When the value `true` is specified, all `.gitignore` files in the tree
+      *and up to the repository root* are used (default `git` behavior)
     - When a `String` value is specified, that glob pattern is used to identify
-      the set of ignore files to import
-      - The value `**/.gitignore` corresponds to the `Boolean` value `true`
-      - The value `.gitignore` imports only the file in the root of the tree;
+      the set of ignore files to use
+      - The value `**/.gitignore` corresponds to the `Boolean` value `true` *but
+        does not use `.gitignore` files up to the repository root*
+      - The value `.gitignore` uses only the file in the root of the tree;
         this is usually equivalent and can be much faster for large trees
     - This top-level setting is valid **only** in the directory from which
       `markdownlint-cli2` is run
@@ -396,15 +448,6 @@ supported by the `--format` command-line parameter. When `--format` is set:
 - For example: [`.markdownlint-cli2.cjs`][markdownlint-cli2-cjs] or
   [`.markdownlint-cli2.mjs`][markdownlint-cli2-mjs]
 
-### `package.json`
-
-- The format of this file is a standard [npm `package.json`][package-json] file
-  including a `markdownlint-cli2` property at the root and a value corresponding
-  to the object described above for `.markdownlint-cli2.jsonc`.
-- `package.json` is only supported in the current directory.
-- `package.json` is not supported by the `--config` argument.
-- For example: [`package-json-sample`][package-json-sample]
-
 ### `.markdownlint.jsonc` or `.markdownlint.json`
 
 - The format of this file is a [JSONC][jsonc] or [JSON][json] object matching
@@ -452,7 +495,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.20.0
+  rev: v0.22.0
   hooks:
   - id: markdownlint-cli2
 ```
@@ -460,6 +503,11 @@ reference to the `repos` list in that project's `.pre-commit-config.yaml` like:
 > Depending on the environment that workflow runs in, it may be necessary to
 > [override the version of Node.js used by pre-commit][pre-commit-version].
 
+Setting the `id` above to `markdownlint-cli2-docker` uses the Docker container
+image instead. That image bundles Node.js and all dependencies and provides the
+most consistent experience because it is not affected by new releases of any
+dependencies.
+
 ## History
 
 See [CHANGELOG.md][changelog].
@@ -467,7 +515,7 @@ See [CHANGELOG.md][changelog].
 [changelog]: CHANGELOG.md
 [command-line]: #command-line
 [commonmark]: https://commonmark.org/
-[commonjs-module]: https://nodejs.org/api/modules.html#modules_modules_commonjs_modules
+[commonjs-module]: https://nodejs.org/api/modules.html#modules-commonjs-modules
 [ecmascript-module]: https://nodejs.org/api/esm.html#modules-ecmascript-modules
 [docker]: https://www.docker.com
 [docker-bind-mounts]: https://docs.docker.com/storage/bind-mounts/
@@ -479,6 +527,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-pointer]: https://datatracker.ietf.org/doc/html/rfc6901
 [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
@@ -514,16 +563,15 @@ See [CHANGELOG.md][changelog].
 [nodejs-docker-non-root]: https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md#non-root-user
 [nodejs-import-expression]: https://nodejs.org/api/esm.html#import-expressions
 [nodejs-import-meta-resolve]: https://nodejs.org/api/esm.html#importmetaresolvespecifier
-[nodejs-require]: https://nodejs.org/api/modules.html#modules_require_id
+[nodejs-require]: https://nodejs.org/api/modules.html#requireid
 [npm-image]: https://img.shields.io/npm/v/markdownlint-cli2.svg
 [npm-url]: https://www.npmjs.com/package/markdownlint-cli2
 [output-formatters]: doc/OutputFormatters.md
-[package-json]: https://docs.npmjs.com/cli/v9/configuring-npm/package-json
-[package-json-sample]: test/package-json/package.json
 [pre-commit]: https://pre-commit.com/
 [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
+[toml]: https://wikipedia.org/wiki/TOML
 [validating-configuration]: schema/ValidatingConfiguration.md
 [vscode]: https://code.visualstudio.com/
 [vscode-markdownlint]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint

package/constants.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+
+const packageName = "markdownlint-cli2";
+const packageVersion = "0.22.0";
+
+const libraryName = "markdownlint";
+
+const cli2SchemaKeys = new Set([
+  "config",
+  "customRules",
+  "fix",
+  "frontMatter",
+  "gitignore",
+  "globs",
+  "ignores",
+  "markdownItPlugins",
+  "modulePaths",
+  "noBanner",
+  "noInlineConfig",
+  "noProgress",
+  "outputFormatters",
+  "showFound"
+]);
+
+export {
+  cli2SchemaKeys,
+  libraryName,
+  packageName,
+  packageVersion
+};