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

@@ -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:

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:<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.

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}/../../)
 

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
-<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.