vale-cli/vale v3.23.0

on GitHub

Vale 3.23.0 reads a Sphinx project as Sphinx does, reads the markup inside source-code comments, and reads large files in linear time.

Sphinx

Docutils knows only its own directives and roles, and dropped the body of every one it did not know, without a word: the prose in every versionadded, seealso, tab, or grid was never linted. Vale now decides the rest by a rule that fits nearly every Sphinx construct: the body of a directive Docutils doesn't define is prose, and the text of a role it doesn't define is code. A :ref: written with a title is linted as its title, and :func:, :class:, and :doc: are left alone. An extension's additions that don't fit the rule go in one section, which the reStructuredText and MyST readers both honor:

[sphinx]
CodeDirectives = mermaid, plantuml
ProseRoles = kbd, samp

Nothing needs Sphinx installed. reStructuredText also reads and writes UTF-8 whatever the console's code page, and the Docutils pool now works on Windows.

Docs: Sphinx

The markup inside comments

A tree-sitter View's per-scope type is honored, so a Rust /// comment is read as Markdown, a Python docstring as reStructuredText, and a Javadoc block as HTML, each with its fenced blocks and inline code skipped:

engine: tree-sitter
scopes:
  - expr: (line_comment)+ @comment
    type: md

Each language's documentation convention is understood on top of that: the name a Go doc comment opens with and its [links], rustdoc and KDoc links, Javadoc and JSDoc tags and @example blocks, and a docstring's :param: fields are not prose. A comment addressed to a tool, //go:build, //nolint, # noqa, eslint-disable, is not read at all. Kotlin and TOML have grammars.

Docs: Code Views, Documentation conventions

Comments in data files

A YAML or TOML file's comments are linted beside the fields its View selects, under the scopes a source file's comments carry, and a # inside a string is not a comment.

Docs: Data Views

Named scopes and metric variables

A scope can be written once in config/scopes/ and used by name in any rule, and doc(...) accepts Selectors Level 4, relative selectors in :has() included:

# styles/config/scopes/Methods.yml
scope: 'doc(section:has(> h2:contains("Methods")))'

A metric formula has the readability scores as variables, quote_words, sentence_length_sd, and round(). A quote scope reaches the text between quotation marks. A rule can carry its own tests:, and vale test --coverage lists the rules without any.

Docs: Named scopes, Selections, metric variables

The package version this Vale supports

vale sync installs the release of a package that the running Vale supports, from a releases manifest in its meta.json or from the package's release feed, so a style that uses a newer key never breaks an older Vale. Built-in rules honor [param] settings, and YES and NO read as booleans.

Docs: The version Vale supports

Formats

• HTML: a page's <meta name="description"> is prose, <samp> is code, and a figure's caption and alt text are no longer skipped with the figure.
• Org: #+TITLE: and #+AUTHOR: are prose, headline tags are not, and a footnote is reported where it is written.
• QDoc: an \omit ... \endomit on one line ends there.
• Plain text: a manuscript's chapters are headings, and metric rules see the file's summary.
• MDX: a code fence after a one-line element stays out of the HTML block.

Changelog

• 2753160 spelling: Read faster on large files, and read figures and inline QDoc omissions
• 75c04b3 feat: Read a data file's comments beside its View, and a page's description
• 0ea6b7a fix: Honor a code View's scope type, mask doc-comment conventions, drop directives, and read Org keywords and footnotes in place
• 521deac fix: scalar settings reach the built-in rules, and YES and NO read as bools
• f8a0142 fix(rst): run the spawned rst2html in Python's UTF-8 mode
• f43fcfc docs: add discord
• 062bf1d fix(rst): read and write UTF-8 whatever the console's code page
• 9a19239 feat: sync installs the release this Vale supports
• 27fa279 fix: give a plain-text file a summary, so metric rules and ls-metrics see it
• 62d4da8 fix: pool Docutils on Windows, where rst2html is a launcher with no shebang
• b66f827 fix(mdx): keep a code fence after a one-line element out of an HTML block (#1194)
• 559bfe1 feat: one [sphinx] section for reStructuredText and MyST
• e435dab fix: place a script rule's matches by the block they index, not the file
• 33087fe feat: read a plain-text manuscript's chapters, and measure speech and pace
• 6ba35ce feat: read the body of a directive Docutils does not know as prose
• 459d3cd feat: Selectors Level 4 in doc(...)
• 0cc85df feat: named scopes, readability variables, and test coverage
• cea3fcd fix: read a YAML file's comments through a tree-sitter View (#1188)
• 706f858 Merge branch 'pr-1192' into v3
• 9bcf8d0 feat(code): add Kotlin comment extraction (#1183)
• 4bd1bc2 fix: place a paragraph that opens with inline content at its own text (#1186)
• b970c75 fix: place a match that wraps into an indented or quoted line (#1185)
• b9f2ee2 fix: locate a match past a multi-byte mask (#1184) (#1193)
• 123e3f9 chore(deps): bump github.com/tomwright/dasel/v3 from 3.10.1 to 3.11.2 (#1190)
• 64d2aa2 ci: allow benchstat to select its required Go toolchain
• 70f3c13 fix: place a summary-scoped alert on the prose it counted
• 275cd4c fix: metric positions in sentence scope
• cac1949 feat: allow metrics to report scoped locations
• 90eaca4 fix: put a fragment file back before the raw scope runs (#1182)
• ba6a2c6 feat: add a quote scope for the text between quotation marks
• 520962e fix: gather a leaf element's own text for a doc(...) selection on it
• 0904d19 feat: accept a selector group at the top level of doc(...)
• 86032fc fix: find a package directory whose case differs from the URL basename