vale

API for declaring a Vale lint aspect that visits markdown files.

First, all markdown sources must be the srcs of some Bazel rule. Either use a filegroup with markdown in the tags:

filegroup(
    name = "md",
    srcs = glob(["*.md"]),
    tags = ["markdown"],
)

or use a markdown_library rule such as the one in https://github.com/dwtj/dwtj_rules_markdown. Aspect plans to provide support for Markdown in configure so these rules can be automatically maintained rather than requiring developers to write them by hand.

Note that any Markdown files in the repo which aren't in the srcs of one of these rules will not be linted by Vale.

Styles

Vale is powered by Styles. There is a built-in style and if this is sufficient then it's not necessary to follow the rest of this section.

The styles from https://vale.sh/hub/ are already fetched by fetch_vale() which has a Bazel-based mirror of https://github.com/errata-ai/packages/blob/master/library.json. It's possible to fetch more styles using a typical http_archive() call.

At runtime, Vale requires the styles are "installed" into a folder together. Use the copy_to_directory rule to accomplish this, for example,

copy_to_directory(
    name = "vale_styles",
    srcs = ["@vale_write-good//:write-good"],
    include_external_repositories = ["vale_*"],
)

Note that the .vale.ini file may have a StylesPath entry. Under Bazel, we set VALE_STYLES_PATH in the environment, so the StylesPath is used only when running Vale outside Bazel, such as in an editor extension.

See the example in rules_lint for a fully-working vale setup.

Usage

load("@aspect_rules_lint//lint:vale.bzl", "vale_aspect")

vale = vale_aspect(
    binary = "@@//tools/lint:vale",
    # A copy_to_bin rule that places the .vale.ini file into bazel-bin
    config = "@@//:.vale_ini",
    # Optional.
    # A copy_to_directory rule that "installs" custom styles together into a single folder
    styles = "@@//tools/lint:vale_styles",
)

Macros and Functions

vale_action

Run Vale as an action under Bazel.

Example usage (generated):

load("@aspect_rules_lint//lint:vale.bzl", "vale_action")

vale_action(
    # Bazel Rule or Aspect evaluation context
    ctx = None,
    # label of the the Vale program
    executable = None,
    # markdown files to be linted
    srcs = [],
    # a directory containing vale extensions, following https://vale.sh/docs/topics/styles/
    styles = None,
    # label of the .vale.ini file, see https://vale.sh/docs/vale-cli/structure/#valeini
    config = None,
    # output file containing stdout of Vale
    stdout = None,
)

ctx

Required.

Bazel Rule or Aspect evaluation context

executable

Required.

label of the the Vale program

srcs

Required.

markdown files to be linted

styles

Required.

a directory containing vale extensions, following https://vale.sh/docs/topics/styles/

config

Required.

label of the .vale.ini file, see https://vale.sh/docs/vale-cli/structure/#valeini

stdout

Required.

output file containing stdout of Vale

exit_code

Optional. Default: None

output file containing Vale exit code. If None, then fail the build when Vale exits non-zero.

output

Optional. Default: "CLI"

the value for the --output flag

env

Optional. Default: {}

environment variables for vale

lint_vale_aspect

A factory function to create a linter aspect.

Example usage (generated):

load("@aspect_rules_lint//lint:vale.bzl", "lint_vale_aspect")

lint_vale_aspect(
    binary = None,
    config = None,
)

binary

Required.

config

Required.

styles

Optional. Default: Label("@aspect_rules_lint//lint:empty_styles")

rule_kinds

Optional. Default: ["markdown_library"]

filegroup_tags

Optional. Default: ["markdown", "lint-with-vale"]

fetch_vale

A repository macro used from WORKSPACE to fetch vale binaries

Example usage (generated):

load("@aspect_rules_lint//lint:vale.bzl", "fetch_vale")

fetch_vale(
)

tag

Optional. Default: "v3.7.0"

a tag of vale that we have mirrored, e.g. v3.0.5