Vale v3.0.0

[jdkato]

Here are some of my rough ideas for the next major release of Vale.

Re-organized StylesPath

The StylesPath will now have a special Vale directory:

Vale
├── dictionaries
├── templates
└── vocabularies

• dictionaries: Hunspell-compatible dictionaries to be loaded by Vale.Spelling. This offers an alternative means of customizing the spell-checking experience in Vale: instead of creating a new rule (e.g., YourStyle.Spelling), you extend the built-in Vale.Spelling with custom dictionaries. This will have the benefit of allowing multiple styles to all contribute to the same spelling rule (Add a way to combine dictionary processing across packages #628).
• templates: Output templates.
• vocabularies: The same as the current Vocab folder; moved to match the new global configuration directories.
  • should be supported in format-specific settings (docs(vocab): Clarify multiple vocabulary usage vale.sh#37)

All of these directories will support being distributed as part of a package.

Default StylesPath + .vale.ini

A configurable location for a default StylesPath (#295) and .vale.ini file. This will allow the following:

1. Package managers will be able to install styles along with the vale executable.
2. Users can choose to use this instead of project-specific configurations.
3. Remote integrations (such as browser extensions) can use this to control their functionality.

Asset management commands

A vale new <asset> commend to:

1. Create a new empty configuration in the current directory if no asset is specified: vale new .
2. Create a new vocabulary: vale new vocabulary <MyVocab>
3. Create a new dictionary: vale new dictionary <MyDict>
4. Create a new template: vale new template <MyTemplate>
5. Create a new style: vale new style <MyStyle>
6. Create a new rule: vale new rule <MyStyle/MyRule.yml>

This will also be supported by vale-ls to allow creating these assets from within your editor.

---

Feel free to comment or suggest other ideas.

[jtiee]

I like this proposal very much.

[ChrisChinchilla]

I also like and it would be a nice feature to wrap in the editor plugins etc

[aireilly]

new asset is a nice feature! Would vale new test-fixture also be useful?

[alexpdp7]

It would be nice to explore decoupling Vale from document formats. For example, we keep much text in YAML files that we would love to run Vale on.

edit: I realize this could be massively complex.

[jdkato]

new asset is a nice feature! Would vale new test-fixture also be useful?

@aireilly, what did you have in mind specifically? The challenge is that Vale would need to know where your tests are stored and how they're structured (neither of which are standardized).

It would be nice to explore decoupling Vale from document formats. For example, we keep much text in YAML files that we would love to run Vale on.

edit: I realize this could be massively complex.

@alexpdp7, can you explain this more? Why can't you run Vale on YAML files?

[alexpdp7]

I can run Vale on YAML files, but that doesn't differentiate "natural language" bits from "identifier" bits. Frequently, in your YAML files, stuff such as the keys might not be correct English (perhaps it's snake_case or camelCase), so this will produce false positives.

You can mitigate that somewhat by extending the vocabularies with the non-words that your YAML files use, or doing stuff like writing something that renders the "natural language" parts of the YAML files to a separate file and running Vale on that.

I think this would be a high-effort, low-impact feature, so I think it might be preferable not to add this to Vale, but if Vale used something like a JavaScript source map (e.g. a file that says "from position x to position y of this file, we have text, in a header scope")¹, it would likely be easy to write source maps generators for any kind of format. Then things like #667, #652, #651, #340, #294 could be externalized and dealt with outside Vale.

Footnotes

1. Also, if you extracted Vale's magical HTML/txt correlation function to produce such source maps, that would be an awesome tool to implement tools similar to Vale- markup processing is a big hurdle for implementing such tools for languages which don't have parsers that generate annotated ASTs, what Vale does is kinda awesome because you can use it to process anything that can render to HTML, and provide line/column information of errors. I think I once found some "standard" text AST/sourcemap format for Markdown/AsciiDoc/etc., but I've never been able to find it again (I think it was some sort of framework for writing prose linters). Writing any tool that deals with text in those requires implementing the parsing/annotation from scratch ↩

[aireilly]

Being able to add Accept and Reject terms to an existing Vocab would be nice.

vale new accept <MyVocab> <NewAcceptTerm>
vale new reject <MyVocab> <NewRejectTerm>

[jdkato]

I'm going to break these changes up into multiple releases, so v3.0.0 will likely only include the "Re-organized StylesPath". The other features will be introduced in subsequent minor versions.

[jdkato]

The first part of this issue, #688 (comment), is pretty much done. You can try it out now by using the v3 branch.

I'll put out a new release once I have the documentation and vale-ls updated.

@andrewvaughan, @karl-johan-grahn

[bollwyvl]

I see #295 is marked as closed.

It looks like still only looks for the user's config dir, and not styles. go stdlib seems to be dragging its feet in implementing the rest of the XDG spec for data (as a separate concept from configuration), while xdg (linked in #295) offers the rest of the paths.

Concretely, I'd like the following workflow to work smoothly to create reproducible environments:

git clone https://example.com/some-project.git
cd some-project

This would contain a description of the environment...

# environment.yml
name: my-env
channels:
  - conda-forge
dependencies:
  - vale ==<some version>
  - vale-microsoft ==<some version>
  - vale-google ==<some version>
  - sphinx

... and a vale.ini, which only needed to reference Google and Microsoft (not full paths):

I'd then like to run:

conda env update       # creates a managed directory somewhere else
# theoretically disconnect from the internet
conda activate my-env  # theoretically set a VALE_STYLES_PATH, unless this can be done at build time
vale <args>            # see results from known version of google, microsoft 

It looks like this could work using relative paths from a61c1d2 if the created environment is guaranteed to be in the repository (e.g. --prefix=./.venv), but having a proper well-known application location for styles, separate from config, would make this the most portable (e.g. on Windows, crazy homebrew stuff, etc).