markdownlint 0.41.0 → 0.42.0

package/doc/md043.md

@@ -6,7 +6,7 @@ Aliases: `required-headings`
 
 Parameters:
 
-- `headings`: List of headings (`string[]`, default `[]`)
+- `headings`: List of headings (`string[]|null`, default `null`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
 This rule is triggered when the headings in a file do not match the array of
@@ -37,13 +37,15 @@ To allow optional headings as with the following structure:
 # Heading
 ## Item
 ### Detail (optional)
+### Example (optional)
 ## Foot
 ### Notes (optional)
 ```
 
-Use the special value `"*"` meaning "zero or more unspecified headings" or the
-special value `"+"` meaning "one or more unspecified headings" and set the
-`headings` parameter to:
+Use the special value `*` meaning "zero or more unspecified headings", the
+special value `+` meaning "one or more unspecified headings", or the special
+value `?` meaning "exactly one unspecified heading" and set the `headings`
+parameter to something like:
 
 ```json
 [
@@ -51,28 +53,64 @@ special value `"+"` meaning "one or more unspecified headings" and set the
     "## Item",
     "*",
     "## Foot",
-    "*"
+    "+"
 ]
 ```
 
-To allow a single required heading to vary as with a project name:
+To require a heading with a specific level and text matching a specific pattern
+(for example, a one-word project name):
 
 ```markdown
-# Project Name
+# Project
 ## Description
 ## Examples
 ```
 
-Use the special value `"?"` meaning "exactly one unspecified heading":
+Replace the `#` prefix character(s) with `%` and specify a regular expression;
+the following example requires a level 1 heading with a single word made up of
+at least 4 letters:
 
 ```json
 [
-    "?",
+    "% [a-zA-Z]{4,}",
     "## Description",
     "## Examples"
 ]
 ```
 
+To handle repeating heading sections (common in `CHANGELOG` files) such as the
+following:
+
+```markdown
+# Changelog
+## 1.0.0
+### Fixes
+### Features
+## 2.0.0
+### Fixes
+### Features
+```
+
+Use the special value `^` meaning "if the next heading does not match, loop
+back to the previous matching marker":
+
+```json
+[
+    "# Changelog",
+    "^",
+    "%% ^\\d+\\.\\d+\\.\\d+$",
+    "### Fixes",
+    "### Features",
+    "^"
+]
+```
+
+The simple form shown above is enough for most scenarios; if multiple loops are
+needed, matching pairs of `^^`, `^^^`, etc. can be used in conjunction. The
+prefix `%` and the special value `?` are supported with loops, but `*` and `+`
+are not and will result in undefined behavior. To avoid infinite looping, a
+violation is reported if the rule loops more than 1,000 times.
+
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).
 

package/doc/md051.md

@@ -13,7 +13,7 @@ Parameters:
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when a link fragment does not match any of the fragments
-that are automatically generated for headings in a document:
+that are automatically generated by GitHub for headings in the document:
 
 ```markdown
 # Heading Name
@@ -31,8 +31,9 @@ generated name (see below):
 ```
 
 For consistency, this rule requires fragments to exactly match the [GitHub
-heading algorithm][github-heading-algorithm] which converts letters to
-lowercase. Therefore, the following example is reported as a violation:
+algorithm for section links][github-section-links] which (among other things)
+converts letters to lowercase. Therefore, the following is reported as a
+violation:
 
 ```markdown
 # Heading Name
@@ -44,9 +45,9 @@ To ignore case when comparing fragments with heading names, the `ignore_case`
 parameter can be set to `true`. In this configuration, the previous example is
 not reported as a violation.
 
-Alternatively, some platforms allow the syntax `{#named-anchor}` to be used
-within a heading to provide a specific name (consisting of only lower-case
-letters, numbers, `-`, and `_`):
+Some platforms allow the syntax `{#named-anchor}` to be used within a heading to
+provide a specific name (consisting of only lower-case letters, numbers, `-`,
+and `_`); that is allowed by this rule:
 
 ```markdown
 # Heading Name {#custom-name}
@@ -63,8 +64,8 @@ attribute can be used to define a fragment:
 [Link](#bookmark)
 ```
 
-An `a` tag can be useful in scenarios where a heading is not appropriate or for
-control over the text of the fragment identifier.
+Using an `a` tag can be useful in scenarios where a heading is not appropriate
+or for control over the text of the fragment identifier.
 
 [HTML links to `#top` scroll to the top of a document][html-top-fragment]. This
 rule allows that syntax (using lower-case for consistency):
@@ -73,16 +74,15 @@ rule allows that syntax (using lower-case for consistency):
 [Link](#top)
 ```
 
-This rule also recognizes the custom fragment syntax used by GitHub to highlight
-[specific content in a document][github-linking-to-content].
-
-For example, this link to line 20:
+This rule supports the fragment syntax used by GitHub to highlight [specific
+lines/sections of a document][github-linking-to-content]. For example, this link
+to line 20:
 
 ```markdown
 [Link](#L20)
 ```
 
-And this link to content starting within line 19 running into line 21:
+And this link to content starting within line 19 running partly through line 21:
 
 ```markdown
 [Link](#L19C5-L21C11)
@@ -91,8 +91,8 @@ And this link to content starting within line 19 running into line 21:
 Some Markdown generators dynamically create and insert headings when building
 documents, for example by combining a fixed prefix like `figure-` and an
 incrementing numeric counter. To ignore such generated fragments, set the
-`ignored_pattern` [regular expression][RegEx] parameter to a pattern that
-matches (e.g., `^figure-`).
+`ignored_pattern` [regular expression][RegEx] parameter to a suitable pattern
+(e.g., `^figure-`).
 
 Rationale: [GitHub section links][github-section-links] are created
 automatically for every heading when Markdown content is displayed on GitHub.
@@ -101,17 +101,17 @@ However, section links change if headings are renamed or removed. This rule
 helps identify broken section links within a document.
 
 Note: Section links are **not** part of the CommonMark specification; this rule
-enforces the [GitHub heading algorithm][github-heading-algorithm]:
+enforces the GitHub algorithm. Basically:
 
 1. Convert text to lowercase
 2. Remove punctuation characters
 3. Convert spaces to dashes
-4. Append an incrementing integer (as needed for uniqueness)
-5. [URI-encode][encodeURIComponent] the result
+4. Remove HTML comments
+5. Append dash+incrementing integer if needed for uniqueness
+6. [URI-encode][encodeURIComponent] the result
 
 [encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
 [github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
-[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
 [github-linking-to-content]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown
 [html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
 [RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions

package/doc/md055.md

@@ -8,15 +8,18 @@ Parameters:
 
 - `style`: Table pipe style (`string`, default `consistent`, values
   `consistent` / `leading_and_trailing` / `leading_only` /
-  `no_leading_or_trailing` / `trailing_only`)
+  `no_leading_or_trailing` / `per_table` / `trailing_only`)
 
 This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
-is inconsistent about its use of leading and trailing pipe characters (`|`).
+is inconsistent with its use of leading and trailing pipe characters (`|`).
 
 By default (`consistent` style), the header row of the first table in a document
 is used to determine the style that is enforced for every table in the document.
 A specific style can be used instead (`leading_and_trailing`, `leading_only`,
-`no_leading_or_trailing`, `trailing_only`).
+`no_leading_or_trailing`, `trailing_only`) to require all tables in a document
+have the same approach. The style `per_table` can be used to require the rows of
+each table use the same approach (based on its header row) while allowing tables
+in a document to differ from each other.
 
 This table's header row has leading and trailing pipes, but its delimiter row is
 missing the trailing pipe and its first row of cells is missing the leading

package/doc/md060.md

@@ -35,7 +35,8 @@ The `aligned` style ignores cell content, so the following is also valid:
 |     N     |      No |
 ```
 
-Style `compact` avoids extra padding with a single space around cell content:
+Style `compact` avoids extra padding with a single space before and after cell
+content (or just a single space for cells without content):
 
 ```markdown
 | Character | Meaning |
@@ -44,7 +45,7 @@ Style `compact` avoids extra padding with a single space around cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding at all for cell content:
+Style `tight` uses no padding at all (for cells with or without content):
 
 ```markdown
 |Character|Meaning|

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.41.0/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/CustomRules.md
 [jsdoc]: https://wikipedia.org/wiki/JSDoc
 [markdown]: https://wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/Rules.md

package/helpers/helpers.cjs

@@ -3,7 +3,6 @@
 "use strict";
 
 const micromark = require("./micromark-helpers.cjs");
-
 const { newlineRe, nextLinesRe } = require("./shared.cjs");
 
 module.exports.newLineRe = newlineRe;
@@ -13,13 +12,14 @@ module.exports.nextLinesRe = nextLinesRe;
 /** @typedef {import("../lib/exports.mjs").RuleOnErrorFixInfo} RuleOnErrorFixInfo */
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} MicromarkToken */
 // eslint-disable-next-line jsdoc/valid-types
-/** @typedef {import("micromark-extension-gfm-footnote", { with: { "resolution-mode": "import" } })} */
+/** @typedef {typeof import("micromark-extension-gfm-footnote", { with: { "resolution-mode": "import" } })} _ambient_ */
 // eslint-disable-next-line jsdoc/valid-types
-/** @typedef {import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} */
+/** @typedef {typeof import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} _ambient_2_ */
 
 // Regular expression for matching common front matter (YAML and TOML)
-// @ts-ignore
+// Potential for regular expression denial of service is mitigated at point-of-use via "re2js" package
 module.exports.frontMatterRe =
+  // eslint-disable-next-line redos/no-vulnerable, unicorn/prefer-unicode-code-point-escapes
   /((^---[^\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;
 
 // Regular expression for matching the start of inline disable/enable comments
@@ -42,6 +42,17 @@ module.exports.allPunctuation = allPunctuation;
 // All punctuation characters without question mark (normal and full-width)
 module.exports.allPunctuationNoQuestion = allPunctuation.replace(/[?？]/gu, "");
 
+/**
+ * Returns true iff the input is a Boolean.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a Boolean.
+ */
+function isBoolean(obj) {
+  return typeof obj === "boolean";
+}
+module.exports.isBoolean = isBoolean;
+
 /**
  * Returns true iff the input is a Number.
  *
@@ -177,7 +188,8 @@ const safeCommentCharacter = ".";
 const startsWithPipeRe = /^ *\|/;
 const notCrLfRe = /[^\r\n]/g;
 const notSpaceCrLfRe = /[^ \r\n]/g;
-const trailingSpaceRe = / +[\r\n]/g;
+const trailingSpaceRe = /(?<=^|[^ ]) +[\r\n]/g;
+// eslint-disable-next-line unicorn/no-unsafe-string-replacement
 const replaceTrailingSpace = (/** @type {string} */ s) => s.replace(notCrLfRe, safeCommentCharacter);
 module.exports.clearHtmlCommentText = function clearHtmlCommentText(/** @type {string} */ text) {
   let i = 0;
@@ -207,7 +219,9 @@ module.exports.clearHtmlCommentText = function clearHtmlCommentText(/** @type {s
       // If a valid block/inline comment...
       if (isValid) {
         const clearedContent = content
+          // eslint-disable-next-line unicorn/no-unsafe-string-replacement
           .replace(notSpaceCrLfRe, safeCommentCharacter)
+          // eslint-disable-next-line unicorn/no-unsafe-string-replacement
           .replace(trailingSpaceRe, replaceTrailingSpace);
         text =
           text.slice(0, i + htmlCommentBegin.length) +
@@ -222,6 +236,7 @@ module.exports.clearHtmlCommentText = function clearHtmlCommentText(/** @type {s
 
 // Escapes a string for use in a RegExp
 module.exports.escapeForRegExp = function escapeForRegExp(/** @type {string} */ str) {
+  // eslint-disable-next-line unicorn/prefer-regexp-escape
   return str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
 };
 
@@ -552,6 +567,7 @@ module.exports.getPreferredLineEnding = getPreferredLineEnding;
  */
 function expandTildePath(file, os) {
   const homedir = os && os.homedir && os.homedir();
+  // eslint-disable-next-line unicorn/no-unsafe-string-replacement
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
@@ -630,8 +646,8 @@ function convertLintErrorsVersion2To0(errors) {
 function copyAndTransformResults(results, transform) {
   /** @type {Object.<string, LintErrors>} */
   const newResults = {};
-  for (const key of Object.keys(results)) {
-    const arr = results[key].map((r) => ({ ...r }));
+  for (const [ key, value ] of Object.entries(results)) {
+    const arr = value.map((r) => ({ ...r }));
     newResults[key] = transform(arr);
   }
   // @ts-ignore

package/helpers/micromark-helpers.cjs

@@ -8,7 +8,7 @@ const { flatTokensSymbol, htmlFlowSymbol, newlineRe } = require("./shared.cjs");
 /** @typedef {import("micromark-util-types", { with: { "resolution-mode": "import" } }).TokenType} TokenType */
 /** @typedef {import("../lib/exports.mjs").MicromarkToken} Token */
 // eslint-disable-next-line jsdoc/valid-types
-/** @typedef {import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} */
+/** @typedef {typeof import("../lib/micromark-types.d.mts", { with: { "resolution-mode": "import" } })} _ambient_ */
 
 /**
  * Determines if a Micromark token is within an htmlFlow type.
@@ -17,8 +17,7 @@ const { flatTokensSymbol, htmlFlowSymbol, newlineRe } = require("./shared.cjs");
  * @returns {boolean} True iff the token is within an htmlFlow type.
  */
 function inHtmlFlow(token) {
-  // @ts-ignore
-  return Boolean(token[htmlFlowSymbol]);
+  return Object.hasOwn(token, htmlFlowSymbol);
 }
 
 /**
@@ -132,10 +131,9 @@ function filterByTypes(tokens, types, htmlFlow) {
   const flatTokens =
     // @ts-ignore
     tokens[flatTokensSymbol];
-  if (flatTokens) {
-    return flatTokens.filter(predicate);
-  }
-  return filterByPredicate(tokens, predicate);
+  return flatTokens ?
+    flatTokens.filter(predicate) :
+    filterByPredicate(tokens, predicate);
 }
 
 /**
@@ -206,10 +204,7 @@ function getHeadingStyle(heading) {
   const atxHeadingSequenceLength = heading.children.filter(
     (child) => child.type === "atxHeadingSequence"
   ).length;
-  if (atxHeadingSequenceLength === 1) {
-    return "atx";
-  }
-  return "atx_closed";
+  return (atxHeadingSequenceLength === 1) ? "atx" : "atx_closed";
 }
 
 /**
@@ -223,7 +218,8 @@ function getHeadingText(heading) {
     .flatMap((descendant) => descendant.children.filter((child) => child.type !== "htmlText"))
     .map((data) => data.text)
     .join("")
-    .replace(newlineRe, " ");
+    .replace(newlineRe, " ")
+    .trim();
 }
 
 /**

package/helpers/package.json

@@ -10,11 +10,7 @@
   "author": "David Anson (https://dlaa.me/)",
   "license": "MIT",
   "homepage": "https://github.com/DavidAnson/markdownlint",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/DavidAnson/markdownlint.git"
-  },
-  "bugs": "https://github.com/DavidAnson/markdownlint/issues",
+  "repository": "github:DavidAnson/markdownlint",
   "funding": "https://github.com/sponsors/DavidAnson",
   "engines": {
     "node": ">=22"

package/helpers/shared.cjs

@@ -2,7 +2,7 @@
 
 "use strict";
 
-// Symbol for identifing the flat tokens array from micromark parse
+// Symbol for identifying the flat tokens array from micromark parse
 module.exports.flatTokensSymbol = Symbol("flat-tokens");
 
 // Symbol for identifying the htmlFlow token from micromark parse

package/lib/cache.mjs

@@ -21,6 +21,7 @@ let params = undefined;
  */
 export function initialize(p) {
   map.clear();
+  // eslint-disable-next-line unicorn/no-top-level-assignment-in-function
   params = p;
 }