-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: convert spelling check to a standard check targets (#118)
* feat: check-spelling command * feat: workdir note comment * refactor: move check-spelling to earthly/cspell * refactor: modify additional comment to arg --src * docs: adding spelling.md into guides * fix: spelling.md sentence length * fix: spelling.md sentence length * fix: change spellcheck guide name * docs: update spellcheck guide * fix: disabling cspell check in overrides section of spellcheck guide * chore: apply markdown format * fix: spellcheck introduction * docs: move readme.md contents from earthly cspell to guides docs * docs: add run locally to the guide * fix: docs line
- Loading branch information
Showing
4 changed files
with
184 additions
and
88 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,157 @@ | ||
--- | ||
icon: material/spellcheck | ||
--- | ||
|
||
# Spell Checking | ||
|
||
## Introduction | ||
|
||
checking is integrated into the `check` pipeline. | ||
The reference to the pipeline can be found [here](https://input-output-hk.github.io/catalyst-ci/onboarding/). | ||
The goal of the `check` stage is to ensure the overall health of the project. | ||
|
||
This utilizes [`cspell`](https://cspell.org) under the hood for checking code and other text documents. | ||
It can be used to check for misspelled words, identify potential errors, and suggest corrections. | ||
|
||
## Using the spell checking | ||
|
||
In an Earthfile in your repo, add the following: | ||
|
||
```earthfile | ||
check-spelling: | ||
DO github.com/input-output-hk/catalyst-ci/earthly/cspell:<tag>+check-spelling | ||
``` | ||
|
||
Executing `earthly +check-spelling` will automatically run the spell checking to all files in the repository. | ||
|
||
### Run locally | ||
|
||
```earthfile | ||
spellcheck-lint: | ||
# Check spelling in this repo. | ||
LOCALLY | ||
DO github.com/input-output-hk/catalyst-ci/earthly/cspell:t1.2.0+CSPELL_LOCALLY --src=$(echo ${PWD}) | ||
``` | ||
|
||
In this use case, the UDC is run Locally, so that the src in the repo can be directly checked. | ||
|
||
## Configuration | ||
|
||
Each repo will need a [`cspell.json`](https://cspell.org/configuration/) file in the root of the repo. | ||
This file configures `cspell`. | ||
The file provided in the `Catalyst-CI` repo should be taken as a starting point | ||
for new projects. | ||
|
||
## Adding specific words to documents | ||
|
||
Words must ONLY be added to document words if they are correctly spelled. | ||
|
||
### Project Words | ||
|
||
It will be necessary for each project to have a list of custom words. | ||
This list extends the list of valid words accepted by the spellchecker. | ||
|
||
These words are added to the file: | ||
|
||
```path | ||
<repo root>/.config/dictionaries/project.dic | ||
``` | ||
|
||
The path can also be configured in the `cspell.json` file. | ||
|
||
```json | ||
"dictionaryDefinitions": [ | ||
{ | ||
"name": "project-words", | ||
"path": ".config/dictionaries/project.dic", | ||
"description": "Words used in this project.", | ||
"addWords": true | ||
} | ||
], | ||
``` | ||
|
||
This can be necessary for the following reasons: | ||
|
||
* The built-in dictionaries do not contain all possible valid words. | ||
* This is especially true when using names of Companies, Products or Technology. | ||
* There are identifiers used in the code which are used which fail spell checks. | ||
|
||
Words must ONLY be added to project words if they are correctly spelled. | ||
|
||
Project words that are added MUST be included in any PR where they became necessary. | ||
PR Review MUST check that the added words are both reasonable and valid. | ||
|
||
Before a word is added to the project dictionary, it should be considered if it is a word likely to occur many times. | ||
|
||
Some spelling errors may only occur once, or a handful of times. | ||
Or, they may be an artifact of the code itself. | ||
In these cases it is MUCH better to disable the spelling error inline rather than add a word to the project dictionary. | ||
See [In Document Settings](http://cspell.org/configuration/document-settings/#in-document-settings) for details. | ||
|
||
### Specific file patterns words | ||
|
||
Custom words and dictionaries for specific file patterns can be configured inside `cspell.json` in the root of the repo. | ||
This can be made by adding `overrides` with custom specifications for specific file patterns. | ||
|
||
<!-- cspell: disable --> | ||
```json | ||
"overrides": [ | ||
{ | ||
"language": "es,es_ES", | ||
"filename": "**/*_es.arb", | ||
"dictionaries": [ | ||
"es-es" | ||
] | ||
}, | ||
{ | ||
"filename": "**/*.pbxproj", | ||
"allowCompoundWords": true, | ||
"words": [ | ||
"iphoneos", | ||
"onone", | ||
"xcassets", | ||
"objc", | ||
"xcconfig", | ||
"lproj", | ||
"libc", | ||
"objc", | ||
"dsym" | ||
] | ||
} | ||
] | ||
``` | ||
<!-- cspell: enable --> | ||
|
||
### Inline specific words | ||
|
||
It is possible to specify custom words within a file by adding comments. | ||
|
||
```text | ||
cspell: words <words> | ||
``` | ||
|
||
Here are some examples for inlining: | ||
|
||
* Comments on Earthfiles | ||
|
||
```earthly | ||
# cspell: words libgcc freetype lcms openjpeg etag | ||
``` | ||
|
||
* Comments on markdown files | ||
|
||
```md | ||
<!-- cspell: words healthcheck isready psql --> | ||
``` | ||
|
||
## Generated Files | ||
|
||
Automatically generated files are likely to contain large amounts of spelling errors. | ||
For these files/paths, exclude them from the spell check by adding their filenames to `"ignorePaths": []` in the `cspell.json` file. | ||
|
||
## Editor Integration | ||
|
||
`cspell` is integrated into VSCode and may be integrated into other Editors. | ||
|
||
The editor integration should pick up the `cspell.json` configuration file and behave exactly the same as the Earthly UDC. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,87 +1,3 @@ | ||
# CSpell Linter | ||
|
||
This Earthly Target and UDC enables uniform spell checking of all source and | ||
documentation files. | ||
|
||
## How it works | ||
|
||
Spellchecking is performed with the [`cspell`](cspell.org) program. | ||
|
||
Use the `CSPELL` Earthly UDC to enable uniform and consistent spell checking. | ||
|
||
This spellchecker is to be used in preference to tool specific spell checkers, | ||
such as `cargo spellcheck`. | ||
This is because we need to provide uniform and consistent spell checking across | ||
multiple source languages and documentation files. | ||
Tool specific spell checkers are limited in the kinds of files they can check, | ||
and also will use different configurations, dictionaries and project word lists. | ||
|
||
## DO NOT RUN AS PART OF A CONTAINER BUILD TARGET | ||
|
||
This UDC is **NOT** intended to be used inside container builds. | ||
Its sole purpose is to enforce uniform and consistent spell checking for all files in a repository. | ||
It makes no assumptions about which files may or may not end up inside a container or are part of a build. | ||
This is *INTENTIONAL*. | ||
|
||
IF this UDC is used inside a container build, it is **NOT** a bug if it does not do the correct thing. | ||
|
||
## Invocation | ||
|
||
In an Earthfile in your repo, add the following: | ||
|
||
```earthfile | ||
spellcheck-lint: | ||
# Check spelling in this repo. | ||
LOCALLY | ||
DO github.com/input-output-hk/catalyst-ci/earthly/cspell:t1.2.0+CSPELL_LOCALLY --src=$(echo ${PWD}) | ||
``` | ||
|
||
In this use case, the UDC is run Locally, so that the src in the repo can be directly checked. | ||
|
||
## Configuration | ||
|
||
Each repo will need a [`cspell.json`](http://cspell.org/configuration/) file in the root of the repo. | ||
This file configures `cspell`. | ||
The file provided in the `Catalyst-CI` repo should be taken as a starting point | ||
for new projects. | ||
|
||
## Project Words | ||
|
||
It will be necessary for each project to have a list of custom words. | ||
This list extends the list of valid words accepted by the spellchecker. | ||
|
||
These words are added to the file: | ||
|
||
```path | ||
<repo root>/.config/dictionaries/project.dic | ||
``` | ||
|
||
This can be necessary for the following reasons: | ||
|
||
* The built-in dictionaries do not contain all possible valid words. | ||
* This is especially true when using names of Companies, Products or Technology. | ||
* There are identifiers used in the code which are used which fail spell checks. | ||
|
||
Words must ONLY be added to project words if they are correctly spelled. | ||
|
||
Project words that are added MUST be included in any PR where they became necessary. | ||
PR Review MUST check that the added words are both reasonable and valid. | ||
|
||
Before a word is added to the project dictionary, it should be considered if it is a word likely to occur many times. | ||
|
||
Some spelling errors may only occur once, or a handful of times. | ||
Or, they may be an artifact of the code itself. | ||
In these cases it is MUCH better to disable the spelling error inline rather than add a word to the project dictionary. | ||
See [In Document Settings](http://cspell.org/configuration/document-settings/#in-document-settings) for details. | ||
|
||
## Generated Files | ||
|
||
Automatically generated files are likely to contain large amounts of spelling errors. | ||
For these files/paths, exclude them from the spell check by adding their filenames to `"ignorePaths": []` in the `cspell.json` file. | ||
|
||
## Editor Integration | ||
|
||
`cspell` is integrated into VSCode and may be integrated into other Editors. | ||
|
||
The editor integration should pick up the `cspell.json` configuration file and behave exactly the same as the Earthly UDC. | ||
See [link](/docs/src/guides/spellcheck.md) for the references. |