One markdown file with unparseable YAML front matter makes check report nothing about any other file in the run, and the payload that comes back does not distinguish that from a clean pass except by a success flag most callers do not read.
What happens
A single file whose front matter contains an unquoted colon:
---
description: this has a colon: right here so it cannot parse
---
Checking a directory of 26 markdown files, 25 of them fine and one of them that:
$ npx @taskless/cli check content/blog --json
{"success":false,"results":[],"failures":["Vale exited 2: E201: yaml: mapping values are not allowed in this context in content/blog/zzz-probe.md"]}results is empty. The 25 good files were never reported on. Exit code is 1 and success is false, so the information is there, but every finding in the run is gone because of one file the run could not read.
How it was found
Onboarding a large markdown vault to Taskless. The first real check after authoring six Vale rules returned zero findings across 328 files, which looked like a clean corpus and was not. Fifteen notes had front matter that could not parse, accumulated over months, and any one of them was enough to zero the run. Every rule over every file had been reporting nothing.
It came back a second time later the same day on a single deliberately broken probe file, which is how the blast radius got measured.
Why this is worth fixing rather than documenting
The create-vale-rule recipe already warns about the shape, under "A single unreadable file fails the whole Vale pass", in the context of extensions needing an external converter. That warning is about a glob the rule author controls. This trigger is different: the author cannot know in advance which of a user's files has a stray colon in its front matter, and a repository accumulates them over time without anyone noticing.
It is also the failure 0.11.1 spent four changesets on, one layer up. A rule that could not be read is now reported as skipped rather than dropped silently. A file that could not be read still takes every other file's findings with it.
The practical consequence is that a checker's silence stops meaning anything. Nobody re-reads a green run.
Suggested fix
Parse front matter before invoking Vale, drop the files that fail, and report each as a per-file finding with its parse error so the run continues over everything else. That keeps one bad file to one finding.
Failing that, degrade rather than abandon: run Vale per file, or retry the batch minus the offender, so results carries what could be checked and failures carries what could not.
A cheaper interim improvement is to make the payload harder to misread. When failures is non-empty, results is not a measurement, and a caller filtering on results alone has no way to see that from the shape of the response.
Repro
- A directory of markdown files with at least one real Vale rule enabled over them
- Add a file whose front matter has an unquoted colon in a value
npx @taskless/cli check <dir> --jsonresults is [], regardless of how many findings the other files hold
Tracked alongside #296 and #297.
One markdown file with unparseable YAML front matter makes
checkreport nothing about any other file in the run, and the payload that comes back does not distinguish that from a clean pass except by asuccessflag most callers do not read.What happens
A single file whose front matter contains an unquoted colon:
Checking a directory of 26 markdown files, 25 of them fine and one of them that:
resultsis empty. The 25 good files were never reported on. Exit code is 1 andsuccessisfalse, so the information is there, but every finding in the run is gone because of one file the run could not read.How it was found
Onboarding a large markdown vault to Taskless. The first real
checkafter authoring six Vale rules returned zero findings across 328 files, which looked like a clean corpus and was not. Fifteen notes had front matter that could not parse, accumulated over months, and any one of them was enough to zero the run. Every rule over every file had been reporting nothing.It came back a second time later the same day on a single deliberately broken probe file, which is how the blast radius got measured.
Why this is worth fixing rather than documenting
The
create-vale-rulerecipe already warns about the shape, under "A single unreadable file fails the whole Vale pass", in the context of extensions needing an external converter. That warning is about a glob the rule author controls. This trigger is different: the author cannot know in advance which of a user's files has a stray colon in its front matter, and a repository accumulates them over time without anyone noticing.It is also the failure 0.11.1 spent four changesets on, one layer up. A rule that could not be read is now reported as skipped rather than dropped silently. A file that could not be read still takes every other file's findings with it.
The practical consequence is that a checker's silence stops meaning anything. Nobody re-reads a green run.
Suggested fix
Parse front matter before invoking Vale, drop the files that fail, and report each as a per-file finding with its parse error so the run continues over everything else. That keeps one bad file to one finding.
Failing that, degrade rather than abandon: run Vale per file, or retry the batch minus the offender, so
resultscarries what could be checked andfailurescarries what could not.A cheaper interim improvement is to make the payload harder to misread. When
failuresis non-empty,resultsis not a measurement, and a caller filtering onresultsalone has no way to see that from the shape of the response.Repro
npx @taskless/cli check <dir> --jsonresultsis[], regardless of how many findings the other files holdTracked alongside #296 and #297.