markdownlint-cli2 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.14.0
+
+- Handle `--` parameter per POSIX convention
+- Add support for glob to `gitignore` configuration
+- Update dependencies (including `markdownlint`)
+
+## 0.13.0
+
+- Add `noBanner` and `gitignore` configuration options
+- Reduce install size by switching to `js-yaml` package
+- Add more detail to some error messages
+- Export JSONC/YAML parsers for reuse
+- Update dependencies (including `markdownlint`)
+
 ## 0.12.1
 
 - Update JSONC parsing to handle trailing commas

package/README.md

@@ -103,6 +103,7 @@ Cross-platform compatibility:
 - Shells that expand globs do not support negated patterns (!node_modules); quoting is required here
 - Some UNIX shells parse exclamation (!) in double-quotes; hashtag (#) is recommended in these cases
 - The path separator is forward slash (/) on all platforms; backslash (\) is automatically converted
+- On any platform, passing the parameter "--" causes all remaining parameters to be treated literally
 
 The most compatible syntax for cross-platform support:
 $ markdownlint-cli2 "**/*.md" "#node_modules"
@@ -147,7 +148,7 @@ 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.12.1 "**/*.md" "#node_modules"
+docker run -v $PWD:/workdir davidanson/markdownlint-cli2:v0.14.0 "**/*.md" "#node_modules"
 ```
 
 Notes:
@@ -164,7 +165,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.12.1 "**/*.md" "#node_modules"
+    docker run -w /myfolder -v $PWD:/myfolder davidanson/markdownlint-cli2:v0.14.0 "**/*.md" "#node_modules"
     ```
 
 For convenience, the container image
@@ -256,6 +257,17 @@ of the rules within.
     - The `String` is passed as the `pattern` parameter to the
       [`RegExp` constructor][regexp-constructor]
     - 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 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;
+        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
   - `globs`: `Array` of `String`s defining glob expressions to append to the
     command-line arguments
     - This setting can be used instead of (or in addition to) passing globs on
@@ -285,6 +297,10 @@ of the rules within.
     - Search [`markdown-it-plugins` on npm][markdown-it-plugins]
   - `modulePaths`: `Array` of `String`s providing additional paths to use when
     resolving module references (e.g., alternate locations for `node_modules`)
+  - `noBanner`: `Boolean` value to disable the display of the banner message and
+    version numbers on `stdout`
+    - This top-level setting is valid **only** in the directory from which
+      `markdownlint-cli2` is run
   - `noInlineConfig`: `Boolean` value to disable the support of
     [HTML comments][html-comment] within Markdown content
     - For example: `<!-- markdownlint-disable some-rule -->`
@@ -396,7 +412,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.12.1
+  rev: v0.14.0
   hooks:
   - id: markdownlint-cli2
 ```

package/append-to-array.js

@@ -6,9 +6,9 @@ const sliceSize = 1000;
 
 /**
  * Efficiently appends the source array to the destination array.
- * @param {Object[]} destination Destination Array.
- * @param {Object[]} source Source Array.
- * @returns void
+ * @param {object[]} destination Destination Array.
+ * @param {object[]} source Source Array.
+ * @returns {void}
  */
 const appendToArray = (destination, source) => {
   // NOTE: destination.push(...source) throws "RangeError: Maximum call stack

package/markdownlint-cli2.js

@@ -26,35 +26,37 @@ const resolveAndRequire = require("./resolve-and-require");
 
 // Variables
 const packageName = "markdownlint-cli2";
-const packageVersion = "0.12.1";
+const packageVersion = "0.14.0";
 const libraryName = "markdownlint";
 const libraryVersion = markdownlintLibrary.getVersion();
+const bannerMessage = `${packageName} v${packageVersion} (${libraryName} v${libraryVersion})`;
 const dotOnlySubstitute = "*.{md,markdown}";
 const utf8 = "utf8";
 
 // No-op function
 const noop = () => null;
 
-// Synchronous function to parse JSONC text
-const jsoncParse = (text) => {
-  const { parse, printParseErrorCode } = require("jsonc-parser");
-  const errors = [];
-  const result = parse(text, errors, { "allowTrailingComma": true });
-  if (errors.length > 0) {
-    const aggregate = errors.map(
-      (err) => `${printParseErrorCode(err.error)} (offset ${err.offset}, length ${err.length})`
-    ).join(", ");
-    throw new Error(`Unable to parse JSON(C) content, ${aggregate}`);
-  }
-  return result;
-};
+// Gets a JSONC parser
+const getJsoncParse = () => require("./parsers/jsonc-parse.js");
+
+// Gets a YAML parser
+const getYamlParse = () => require("./parsers/yaml-parse.js");
 
-// Synchronous function to parse YAML text
-const yamlParse = (text) => require("yaml").parse(text);
+// Gets an ordered array of parsers
+const getParsers = () => require("./parsers/parsers.js");
 
-// Negate a glob
+// Negates a glob
 const negateGlob = (glob) => `!${glob}`;
 
+// Throws a meaningful exception for an unusable configuration file
+const throwForConfigurationFile = (file, error) => {
+  throw new Error(
+    `Unable to use configuration file '${file}'; ${error?.message}`,
+    // @ts-ignore
+    { "cause": error }
+  );
+};
+
 // Return a posix path (even on Windows)
 const posixPath = (p) => p.split(pathDefault.sep).join(pathPosix.sep);
 
@@ -69,13 +71,13 @@ const resolveModulePaths = (dir, modulePaths) => (
 );
 
 // Read a JSON(C) or YAML file and return the object
-const readConfig = (fs, dir, name, otherwise) => {
+const readConfig = (fs, dir, name, otherwise) => () => {
   const file = pathPosix.join(dir, name);
-  return () => fs.promises.access(file).
+  return fs.promises.access(file).
     then(
       () => markdownlintReadConfig(
         file,
-        [ jsoncParse, yamlParse ],
+        getParsers(),
         fs
       ),
       otherwise
@@ -83,11 +85,12 @@ const readConfig = (fs, dir, name, otherwise) => {
 };
 
 // Import or resolve/require a module ID with a custom directory in the path
-const importOrRequireResolve = async (dirs, id, noRequire) => {
+const importOrRequireResolve = async (dirOrDirs, id, noRequire) => {
   if (typeof id === "string") {
     if (noRequire) {
       return null;
     }
+    const dirs = Array.isArray(dirOrDirs) ? dirOrDirs : [ dirOrDirs ];
     const expandId = expandTildePath(id);
     const errors = [];
     try {
@@ -96,10 +99,13 @@ const importOrRequireResolve = async (dirs, id, noRequire) => {
       errors.push(error);
     }
     try {
-      const fileUrlString =
-        pathToFileURL(pathDefault.resolve(dirs[0], expandId)).toString();
+      // eslint-disable-next-line n/no-unsupported-features/node-builtins
+      const isURL = !pathDefault.isAbsolute(expandId) && URL.canParse(expandId);
+      const urlString = (
+        isURL ? new URL(expandId) : pathToFileURL(pathDefault.resolve(dirs[0], expandId))
+      ).toString();
       // eslint-disable-next-line no-inline-comments
-      const module = await import(/* webpackIgnore: true */ fileUrlString);
+      const module = await import(/* webpackIgnore: true */ urlString);
       return module.default;
     } catch (error) {
       errors.push(error);
@@ -133,11 +139,11 @@ const importOrRequireIdsAndParams = (dirs, idsAndParams, noRequire) => (
 );
 
 // Import or require a JavaScript file and return the exported object
-const importOrRequireConfig = (fs, dir, name, noRequire, otherwise) => {
-  const id = pathPosix.join(dir, name);
-  return () => fs.promises.access(id).
+const importOrRequireConfig = (fs, dir, name, noRequire, otherwise) => () => {
+  const file = pathPosix.join(dir, name);
+  return fs.promises.access(file).
     then(
-      () => (noRequire ? {} : importOrRequireResolve([ dir ], id)),
+      () => importOrRequireResolve(dir, name, noRequire),
       otherwise
     );
 };
@@ -148,7 +154,7 @@ const getExtendedConfig = (config, configPath, fs) => {
     return markdownlintExtendConfig(
       config,
       configPath,
-      [ jsoncParse, yamlParse ],
+      getParsers(),
       fs
     );
   }
@@ -162,47 +168,43 @@ const readOptionsOrConfig = async (configPath, fs, noRequire) => {
   const dirname = pathPosix.dirname(configPath);
   let options = null;
   let config = null;
-  if (basename.endsWith(".markdownlint-cli2.jsonc")) {
-    options = jsoncParse(await fs.promises.readFile(configPath, utf8));
-  } else if (basename.endsWith(".markdownlint-cli2.yaml")) {
-    options = yamlParse(await fs.promises.readFile(configPath, utf8));
-  } else if (
-    basename.endsWith(".markdownlint-cli2.cjs") ||
-    basename.endsWith(".markdownlint-cli2.mjs")
-  ) {
-    options = await (
-      importOrRequireConfig(fs, dirname, basename, noRequire, noop)()
-    );
-  } else if (
-    basename.endsWith(".markdownlint.jsonc") ||
-    basename.endsWith(".markdownlint.json") ||
-    basename.endsWith(".markdownlint.yaml") ||
-    basename.endsWith(".markdownlint.yml")
-  ) {
-    config =
-      await markdownlintReadConfig(configPath, [ jsoncParse, yamlParse ], fs);
-  } else if (
-    basename.endsWith(".markdownlint.cjs") ||
-    basename.endsWith(".markdownlint.mjs")
-  ) {
-    config = await (
-      importOrRequireConfig(fs, dirname, basename, noRequire, noop)()
-    );
-  } else {
-    throw new Error(
-      `Configuration file "${configPath}" is unrecognized; ` +
-      "its name should be (or end with) one of the supported types " +
-      "(e.g., \".markdownlint.json\" or \"example.markdownlint-cli2.jsonc\")."
-    );
+  try {
+    if (basename.endsWith(".markdownlint-cli2.jsonc")) {
+      options = getJsoncParse()(await fs.promises.readFile(configPath, utf8));
+    } else if (basename.endsWith(".markdownlint-cli2.yaml")) {
+      options = getYamlParse()(await fs.promises.readFile(configPath, utf8));
+    } else if (
+      basename.endsWith(".markdownlint-cli2.cjs") ||
+      basename.endsWith(".markdownlint-cli2.mjs")
+    ) {
+      options = await importOrRequireResolve(dirname, basename, noRequire);
+    } else if (
+      basename.endsWith(".markdownlint.jsonc") ||
+      basename.endsWith(".markdownlint.json") ||
+      basename.endsWith(".markdownlint.yaml") ||
+      basename.endsWith(".markdownlint.yml")
+    ) {
+      config = await markdownlintReadConfig(configPath, getParsers(), fs);
+    } else if (
+      basename.endsWith(".markdownlint.cjs") ||
+      basename.endsWith(".markdownlint.mjs")
+    ) {
+      config = await importOrRequireResolve(dirname, basename, noRequire);
+    } else {
+      throw new Error(
+        "File name should be (or end with) one of the supported types " +
+        "(e.g., '.markdownlint.json' or 'example.markdownlint-cli2.jsonc')."
+      );
+    }
+  } catch (error) {
+    throwForConfigurationFile(configPath, error);
   }
-
   if (options) {
     if (options.config) {
       options.config = await getExtendedConfig(options.config, configPath, fs);
     }
     return options;
   }
-
   config = await getExtendedConfig(config, configPath, fs);
   return { config };
 };
@@ -241,7 +243,10 @@ const processArgv = (argv) => {
 };
 
 // Show help if missing arguments
-const showHelp = (logMessage) => {
+const showHelp = (logMessage, showBanner) => {
+  if (showBanner) {
+    logMessage(bannerMessage);
+  }
   logMessage(`https://github.com/DavidAnson/markdownlint-cli2
 
 Syntax: markdownlint-cli2 glob0 [glob1] [...] [globN] [--config file] [--fix] [--help]
@@ -280,6 +285,7 @@ Cross-platform compatibility:
 - Shells that expand globs do not support negated patterns (!node_modules); quoting is required here
 - Some UNIX shells parse exclamation (!) in double-quotes; hashtag (#) is recommended in these cases
 - The path separator is forward slash (/) on all platforms; backslash (\\) is automatically converted
+- On any platform, passing the parameter "--" causes all remaining parameters to be treated literally
 
 The most compatible syntax for cross-platform support:
 $ markdownlint-cli2 "**/*.md" "#node_modules"`
@@ -297,6 +303,7 @@ const getAndProcessDirInfo = (
   noRequire,
   allowPackageJson
 ) => {
+  // Create dirInfo
   let dirInfo = dirToDirInfo[dir];
   if (!dirInfo) {
     dirInfo = {
@@ -310,46 +317,41 @@ const getAndProcessDirInfo = (
     dirToDirInfo[dir] = dirInfo;
 
     // Load markdownlint-cli2 object(s)
-    const markdownlintCli2Jsonc =
-      pathPosix.join(dir, ".markdownlint-cli2.jsonc");
-    const markdownlintCli2Yaml =
-      pathPosix.join(dir, ".markdownlint-cli2.yaml");
+    const markdownlintCli2Jsonc = pathPosix.join(dir, ".markdownlint-cli2.jsonc");
+    const markdownlintCli2Yaml = pathPosix.join(dir, ".markdownlint-cli2.yaml");
+    const markdownlintCli2Cjs = pathPosix.join(dir, ".markdownlint-cli2.cjs");
+    const markdownlintCli2Mjs = pathPosix.join(dir, ".markdownlint-cli2.mjs");
     const packageJson = pathPosix.join(dir, "package.json");
+    let file = "[UNKNOWN]";
+    // eslint-disable-next-line no-return-assign
+    const captureFile = (f) => file = f;
     tasks.push(
-      fs.promises.access(markdownlintCli2Jsonc).
+      fs.promises.access(captureFile(markdownlintCli2Jsonc)).
         then(
-          () => fs.promises.
-            readFile(markdownlintCli2Jsonc, utf8).
-            then(jsoncParse),
-          () => fs.promises.access(markdownlintCli2Yaml).
+          () => fs.promises.readFile(file, utf8).then(getJsoncParse()),
+          () => fs.promises.access(captureFile(markdownlintCli2Yaml)).
             then(
-              () => fs.promises.
-                readFile(markdownlintCli2Yaml, utf8).
-                then(yamlParse),
-              importOrRequireConfig(
-                fs,
-                dir,
-                ".markdownlint-cli2.cjs",
-                noRequire,
-                importOrRequireConfig(
-                  fs,
-                  dir,
-                  ".markdownlint-cli2.mjs",
-                  noRequire,
-                  () => (allowPackageJson
-                    ? fs.promises.access(packageJson)
-                    // eslint-disable-next-line prefer-promise-reject-errors
-                    : Promise.reject()
-                  ).
+              () => fs.promises.readFile(file, utf8).then(getYamlParse()),
+              () => fs.promises.access(captureFile(markdownlintCli2Cjs)).
+                then(
+                  () => importOrRequireResolve(dir, file, noRequire),
+                  () => fs.promises.access(captureFile(markdownlintCli2Mjs)).
                     then(
-                      () => fs.promises.
-                        readFile(packageJson, utf8).
-                        then(jsoncParse).
-                        then((obj) => obj[packageName]),
-                      noop
+                      () => importOrRequireResolve(dir, file, noRequire),
+                      () => (allowPackageJson
+                        ? fs.promises.access(captureFile(packageJson))
+                        // eslint-disable-next-line prefer-promise-reject-errors
+                        : Promise.reject()
+                      ).
+                        then(
+                          () => fs.promises.
+                            readFile(file, utf8).
+                            then(getJsoncParse()).
+                            then((obj) => obj[packageName]),
+                          noop
+                        )
                     )
                 )
-              )
             )
         ).
         then((options) => {
@@ -358,13 +360,16 @@ const getAndProcessDirInfo = (
             options.config &&
             getExtendedConfig(
               options.config,
-              // Just needs to identify a file in the right directory
+              // Just need to identify a file in the right directory
               markdownlintCli2Jsonc,
               fs
             ).
               then((config) => {
                 options.config = config;
               });
+        }).
+        catch((error) => {
+          throwForConfigurationFile(file, error);
         })
     );
 
@@ -410,6 +415,8 @@ const getAndProcessDirInfo = (
         })
     );
   }
+
+  // Return dirInfo
   return dirInfo;
 };
 
@@ -471,14 +478,19 @@ const enumerateFiles = async (
   baseDir,
   globPatterns,
   dirToDirInfo,
+  gitignore,
+  ignoreFiles,
   noRequire
 ) => {
   const tasks = [];
+  /** @type {import("globby").Options} */
   const globbyOptions = {
     "absolute": true,
     "cwd": baseDir,
     "dot": true,
     "expandDirectories": false,
+    gitignore,
+    ignoreFiles,
     "suppressErrors": true,
     fs
   };
@@ -603,6 +615,8 @@ const createDirInfos = async (
   globPatterns,
   dirToDirInfo,
   optionsOverride,
+  gitignore,
+  ignoreFiles,
   noRequire
 ) => {
   await enumerateFiles(
@@ -611,6 +625,8 @@ const createDirInfos = async (
     baseDir,
     globPatterns,
     dirToDirInfo,
+    gitignore,
+    ignoreFiles,
     noRequire
   );
   await enumerateParents(
@@ -767,7 +783,7 @@ const lintFiles = (fs, dirInfos, fileContents) => {
       "files": filteredFiles,
       "strings": filteredStrings,
       "config": markdownlintConfig || markdownlintOptions.config,
-      "configParsers": [ jsoncParse, yamlParse ],
+      "configParsers": getParsers(),
       "customRules": markdownlintOptions.customRules,
       "frontMatter": markdownlintOptions.frontMatter
         ? new RegExp(markdownlintOptions.frontMatter, "u")
@@ -902,52 +918,52 @@ const main = async (params) => {
     (directory && pathDefault.resolve(directory)) ||
     process.cwd();
   const baseDir = posixPath(baseDirSystem);
-  // Output banner
-  logMessage(
-    `${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 sawDashDash = false;
   let shouldShowHelp = false;
   const argvFiltered = (argv || []).filter((arg) => {
-    if (configPath === null) {
+    if (sawDashDash) {
+      return true;
+    } else if (configPath === null) {
       configPath = arg;
-      return false;
       // eslint-disable-next-line unicorn/prefer-switch
+    } else if (arg === "--") {
+      sawDashDash = true;
     } 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;
+    } else {
+      return true;
     }
-    return true;
+    return false;
   });
   if (shouldShowHelp) {
-    return showHelp(logMessage);
+    return showHelp(logMessage, true);
   }
   // Read argv configuration file (if relevant and present)
   let optionsArgv = null;
   let relativeDir = null;
-  if (configPath) {
-    const resolvedConfigPath =
-      posixPath(pathDefault.resolve(baseDirSystem, configPath));
-    optionsArgv =
-      await readOptionsOrConfig(resolvedConfigPath, fs, noRequire);
-    relativeDir = pathPosix.dirname(resolvedConfigPath);
-  }
-  // Process arguments and get base options
-  const globPatterns = processArgv(argvFiltered);
-  const { baseMarkdownlintOptions, dirToDirInfo } =
-    await getBaseOptions(
+  let globPatterns = null;
+  let baseOptions = null;
+  try {
+    if (configPath) {
+      const resolvedConfigPath =
+        posixPath(pathDefault.resolve(baseDirSystem, configPath));
+      optionsArgv =
+        await readOptionsOrConfig(resolvedConfigPath, fs, noRequire);
+      relativeDir = pathPosix.dirname(resolvedConfigPath);
+    }
+    // Process arguments and get base options
+    globPatterns = processArgv(argvFiltered);
+    baseOptions = await getBaseOptions(
       fs,
       baseDir,
       relativeDir,
@@ -957,13 +973,19 @@ const main = async (params) => {
       noGlobs,
       noRequire
     );
+  } finally {
+    if (!baseOptions?.baseMarkdownlintOptions.noBanner) {
+      logMessage(bannerMessage);
+    }
+  }
   if (
     ((globPatterns.length === 0) && !nonFileContents) ||
     (configPath === null)
   ) {
-    return showHelp(logMessage);
+    return showHelp(logMessage, false);
   }
   // Include any file overrides or non-file content
+  const { baseMarkdownlintOptions, dirToDirInfo } = baseOptions;
   const resolvedFileContents = {};
   for (const file in fileContents) {
     const resolvedFile = posixPath(pathDefault.resolve(baseDirSystem, file));
@@ -983,6 +1005,13 @@ const main = async (params) => {
     logMessage(`Finding: ${globPatterns.join(" ")}`);
   }
   // Create linting tasks
+  const gitignore =
+    // https://github.com/sindresorhus/globby/issues/265
+    (!params.fs && (baseMarkdownlintOptions.gitignore === true));
+  const ignoreFiles =
+    (!params.fs && (typeof baseMarkdownlintOptions.gitignore === "string"))
+      ? baseMarkdownlintOptions.gitignore
+      : undefined;
   const dirInfos =
     await createDirInfos(
       fs,
@@ -991,6 +1020,8 @@ const main = async (params) => {
       globPatterns,
       dirToDirInfo,
       optionsOverride,
+      gitignore,
+      ignoreFiles,
       noRequire
     );
   // Output linting status

package/merge-options.js

@@ -4,9 +4,9 @@
 
 /**
  * Merges two options objects by combining config and replacing properties.
- * @param {Object} first First options object.
- * @param {Object} second Second options object.
- * @returns {Object} Merged options object.
+ * @param {object} first First options object.
+ * @param {object} second Second options object.
+ * @returns {object} Merged options object.
  */
 const mergeOptions = (first, second) => {
   const merged = {