Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

fix(lint): correct four Vale behaviours the skills described wrongly

Browse Source 
Each of these would send a user down a path Vale does not support:

Core options placed under a glob header are not scoped to that glob — Vale
rejects them with E201, so the guidance to nest them produced a config that
will not load. The built-in `Vale` style is compiled in, but Vale still
requires StylesPath to exist on disk before it will run, so the "no StylesPath
needed" shortcut fails. The MDX guidance was inverted: under `[formats]
mdx = md` the mapping is what makes MDX lint at all, and it needs the mdx2vast
prerequisite that was never mentioned. And a spelling rule's `ignore` paths
resolve against StylesPath, not against the rule file's own directory, so the
documented relative paths silently matched nothing.
This commit is contained in:
Defame1297
2026-08-31 08:01:26 +00:00
parent 27a76692b0
commit b07d54ad7a
12 changed files with 224 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
plugins/lint/skills/vale-run/references/sources.md
View File

@@ -7,3 +7,11 @@
- **Research doc:** plugins/lint/docs/research/docs/vale/sources.md
- **Contributing files:** SKILL.md, references/troubleshooting.md
- **Status:** `extracted`
## house-vale-3-15-2-repro
- **URL:** (house-verified — reproduced locally against the `vale` binary, not an external source)
- **Description:** Behaviour of Vale 3.15.2 established by running it against purpose-built fixtures in this repo, where vale.sh documents nothing or documents it wrongly: `.mdx` has no built-in support and needs either `[formats] mdx = md` or an external `mdx2vast` binary (absent, the whole invocation exits 2 with `E100 [lintMDX]`), the inline-suppression form inverts between those two configurations, the `spelling` check's `ignore` paths resolve against `StylesPath` or the working directory but never against the rule file's own directory and fail silently when they resolve nowhere, `ls-config` reports styles and paths but never rules, and the `text.frontmatter.<key>` scope matrix across multi-line YAML forms.
- **Research doc:** none — house-verified reproduction, not part of the plugin's research corpus (no `plugins/lint/docs/research/` topic file backs this entry)
- **Contributing files:** SKILL.md, references/troubleshooting.md
- **Status:** `extracted`

91
plugins/lint/skills/vale-run/references/troubleshooting.md
View File

@@ -1,6 +1,7 @@
---
source_keys:
- context7-websites-vale-sh
- house-vale-3-15-2-repro
---
# Vale troubleshooting reference
@@ -9,19 +10,68 @@ source_keys:
`vale ls-config` prints the fully-resolved, currently active configuration as JSON. Check that
before rereading `.vale.ini` — what is written in the config file is not necessarily what is
active, and the resolved output is the fastest way to see which styles and rules a run actually
loaded.
active, and the resolved output is the fastest way to see which config files, styles and
`StylesPath` directories a run actually loaded.
It stops at styles. It does not enumerate rules, and neither does any other Vale 3.15.2
subcommand — `ls-config`, `ls-dirs`, `ls-vars` and `ls-metrics` were each checked and none
names the rule. Against a config
whose custom rule was demonstrably firing on the target file, `ls-config` reported
`"SBaseStyles": {"*.md": ["MyStyle"]}` and the two `StylesPath` search paths, but
`"Checks": null`, `"SChecks": {"*.md": {}}` and `"RuleToLevel": {}` — the firing rule's own name
appeared nowhere in the output. So `ls-config` answers "is this style loaded, and from where",
not "is this rule live". For the latter, run Vale over a small fixture that should trigger the
rule and see whether it alerts.
## Inline suppression syntax by format
Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file:
### Prerequisite: `.mdx` needs a decision before it lints at all
Vale 3.15.2 has no built-in MDX support. If `.vale.ini` does **not** map the extension, Vale takes
the native MDX path and shells out to an external `mdx2vast` binary. Without it on `PATH` the run
dies before linting anything:
```
$ vale . # doc.md and doc.mdx both present, no [formats] mapping
E100 [lintMDX] Runtime error
mdx2vast not found
Execution stopped with code 1.
$ echo $?
2
```
That is the whole invocation, not just the `.mdx` file — the `.md` alongside it produced no output
either. Fix it one of two ways, and the choice is not cosmetic because it also decides the
suppression syntax:
| `.vale.ini` | Prerequisite | Parser | Suppression form that works |
|---|---|---|---|
| `[formats]` maps `mdx = md` (what `vale-config` recommends) | none | Markdown | `<!-- vale off -->` |
| no `mdx` mapping (native MDX) | `npm install -g mdx2vast` | MDX | `{/* vale off */}` |
Key the markup to that config row, never to the file extension. Verified against Vale 3.15.2, same
three fixtures under each config:
| File | Mapped `mdx = md` | Native MDX (`mdx2vast` installed) |
|---|---|---|
| no suppression (control) | alert, exit 1 | alert, exit 1 |
| `<!-- vale off -->` | suppressed, exit 0 | `E100 ... failed to parse MDX: Unexpected character` `` `!` ``, exit 2 |
| `{/* vale off */}` | **not suppressed**, exit 1 | suppressed, exit 0 |
Under the mapping the JSX comment is worse than inert: it is linted as prose, so
`{/* vale Vale.Repetition = NO */}` produced three alerts where the un-suppressed file produced
one — its own markup tripped the rule twice more.
Markdown, and `.mdx` mapped onto it — HTML comments:
```markdown
<!-- vale off -->
This text will be ignored.
<!-- vale on -->
```
MDX:
Native MDX only (no `[formats]` mapping, `mdx2vast` on `PATH`):
```mdx
{/* vale off */}
This text will be ignored.
@@ -46,7 +96,8 @@ This is some text ACT test
<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->
```
MDX:
Native MDX only — under `[formats] mdx = md` an `.mdx` file takes the Markdown form above, and
this one silences nothing:
```mdx
{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
This is some text ACT test
@@ -66,6 +117,36 @@ ignore:
- ignore2.txt
```
**Where the file goes, and why a wrong answer is invisible.** Each entry resolves against the
`StylesPath` root, or against the working directory `vale` is invoked from. It does **not** resolve
against the rule file's own directory — which is the natural reading of the YAML above, since the
path sits inside the rule, and it is wrong. Verified against Vale 3.15.2 across four fresh trees,
each with the same rule and the same unknown word:
| Where `ignore1.txt` was placed | Result |
|---|---|
| `<StylesPath>/ignore1.txt` | word ignored, exit 0 |
| `./ignore1.txt` in the directory `vale` runs from | word ignored, exit 0 |
| `<StylesPath>/<Style>/ignore1.txt`, beside the rule | word still flagged, exit 1 |
| file absent entirely | word still flagged, exit 1 |
The two failing rows emit no warning, no error, and no diagnostic of any kind: the output is
byte-identical to the same rule with the `ignore` key deleted. A misplaced ignore list looks exactly
like a list that was read and did not contain the word.
Prefer the `StylesPath` root. The run-directory form is the fragile one — move the invocation and it
silently stops working. Same tree, same file, only the working directory changed:
```
$ cd project && vale doc.md # ignore1.txt at project root
✔ 0 errors, 0 warnings and 0 suggestions in 1 file. # exit 0
$ cd /elsewhere && vale --config=project/.vale.ini project/doc.md
1:5 error Did you really mean 'zzqwidget'? MyStyle.Spell # exit 1
```
The `StylesPath` copy survives that move; the run-directory copy does not.
## Plain-text fallback
If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.