Allow custom rules to report and fix errors in front matter

[todesking]

I'm writing a custom rule that validates front matter content (for example, requiring a title key and checking date formats).

As noted in #1202, a custom rule can inspect front matter via params.frontMatterLines. However, there is currently no way to report an error at a precise location within the front matter, nor to fix it: onError only accepts lineNumber values that refer to params.lines (the Markdown body), and fixInfo is likewise limited to body lines.

I'd like to propose a small, opt-in extension to RuleOnErrorInfo:

onError({
  frontMatter: true, // new: lineNumber refers to params.frontMatterLines
  lineNumber: 2,     // 1-based index into frontMatterLines
  range: [1, 5],
  fixInfo: { editColumn: 1, deleteCount: 5, insertText: "title" }
});

When frontMatter is true:

• lineNumber (and fixInfo.lineNumber, if specified) are validated against frontMatterLines.length instead of lines.length; when producing the absolute file line number, the usual front matter offset is not added
• range, fixInfo.editColumn, and fixInfo.deleteCount are validated against the corresponding line in frontMatterLines
• Using frontMatter: true when there is no front matter fails validation, consistent with other onError validation

As far as I can tell, no change to the output format is needed: LintError.lineNumber is already absolute within the file, and applyFixes already operates on the full input, including front matter. Existing rules would be unaffected because the flag is opt-in.

One implementation detail is enabledRulesPerLineNumber: its entries corresponding to front matter are currently empty, so the rule-enablement check in onError would also need to account for front matter errors.

What do you think of this approach? If it sounds reasonable, I'd be happy to open a pull request.

[DavidAnson]

What you propose makes sense, thank you for describing it in detail. I worry a little that this expands the scope of the tool for a very limited set of scenarios (2 requests ever), but I can't come up with a significant objection.

Notes:

I'll be picky enough about the implementation that you may want to let me do it instead of via PR. I could get to it in the next two-ish weeks if we agree on everything.

I'm curious if you know of any other tools that do such a thing?

I would not want to introduce syntax for enabling or disabling rules within front matter, but rely on the existing file-based mechanisms instead.

Dealing with different front manner formats and languages is not something I want to support. My thinking is to expose it as text (like you propose) and leave parsing/formatting up to the custom rule.

[todesking]

Thanks, that all sounds good to me.

I'm happy to leave the implementation to you. There's no urgency on my side, so the next couple of weeks are perfectly fine.

I agree that enabling/disabling rules within front matter itself would be unnecessary. Relying on the existing file-level mechanisms seems like the right behavior.

I also agree that markdownlint shouldn't need to understand YAML, TOML, or any other front matter format. Exposing the text and allowing custom rules to parse and validate it is exactly what I had in mind.

As for similar tools, the closest example I know of is the remark ecosystem. remark-frontmatter represents front matter as a syntax node with source position information, but deliberately does not parse its contents as YAML/TOML; plugins are responsible for that. There is also remark-lint-frontmatter-schema, which builds on this to validate YAML front matter and can report diagnostics at precise locations within it (and provide fix suggestions).

So that seems fairly similar in terms of the separation of responsibilities, although the APIs are, of course, quite different.

Thanks for considering this!