From f888a896bf4c1db2538e4eec47c68c6bdd0736df Mon Sep 17 00:00:00 2001 From: Apisit Ritreungroj <38898766+apskhem@users.noreply.github.com> Date: Wed, 6 Dec 2023 22:33:22 +0700 Subject: [PATCH] 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 --- Earthfile | 9 +- docs/src/guides/spellcheck.md | 157 ++++++++++++++++++++++++++++++++++ earthly/cspell/Earthfile | 20 ++++- earthly/cspell/Readme.md | 86 +------------------ 4 files changed, 184 insertions(+), 88 deletions(-) create mode 100644 docs/src/guides/spellcheck.md diff --git a/Earthfile b/Earthfile index 681554ef3..767ca9166 100644 --- a/Earthfile +++ b/Earthfile @@ -20,20 +20,25 @@ markdown-check-fix: DO ./earthly/mdlint+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix +# spell-check Check spelling in this repo locally. spell-check: - # Check spelling in this repo. LOCALLY DO ./earthly/cspell+CSPELL_LOCALLY --src=$(echo ${PWD}) +# check-spelling Check spelling in this repo inside a container. +check-spelling: + DO ./earthly/cspell+CHECK + ## ----------------------------------------------------------------------------- ## ## Standard CI targets. ## ## These targets are discovered and executed automatically by CI. -# check - run all checks. +# check run all checks. check: + BUILD +check-spelling BUILD +check-markdown repo-docs: diff --git a/docs/src/guides/spellcheck.md b/docs/src/guides/spellcheck.md new file mode 100644 index 000000000..81d7b74b9 --- /dev/null +++ b/docs/src/guides/spellcheck.md @@ -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:+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 +/.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. + + +```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" + ] + } +] +``` + + +### Inline specific words + +It is possible to specify custom words within a file by adding comments. + +```text +cspell: words +``` + +Here are some examples for inlining: + +* Comments on Earthfiles + +```earthly +# cspell: words libgcc freetype lcms openjpeg etag +``` + +* Comments on markdown files + +```md + +``` + +## 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. diff --git a/earthly/cspell/Earthfile b/earthly/cspell/Earthfile index 57901e427..a0f0f508d 100644 --- a/earthly/cspell/Earthfile +++ b/earthly/cspell/Earthfile @@ -24,10 +24,28 @@ CSPELL_LOCALLY: ghcr.io/streetsidesoftware/cspell:8.0.0 \ lint . --dot +CHECK: + # Spell checking all docs and code is done with cspell + # See: cspell.org + COMMAND + + # Where we want to run the `lint` from. Use `.` to check the whole repo. + ARG src=. + + # Unlikely to need to change this. + ARG cfg_file=cspell.json + + FROM ghcr.io/streetsidesoftware/cspell:8.0.0 + WORKDIR /work + + COPY $src . + + RUN cspell-cli lint . --dot + # A Test and example invocation of the above UDC. cspell-test: # As notes above, this check must only be run locally. LOCALLY - # Run with `earthly -P +cspell-test + # Run with `earthly -P +cspell-test` DO +CSPELL_LOCALLY --src=$(echo ${PWD}/../../) diff --git a/earthly/cspell/Readme.md b/earthly/cspell/Readme.md index f353ac298..0296fd1a9 100644 --- a/earthly/cspell/Readme.md +++ b/earthly/cspell/Readme.md @@ -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 -/.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.