Spell Checking¶

Introduction¶

checking is integrated into the check pipeline. The reference to the pipeline can be found here. The goal of the check stage is to ensure the overall health of the project.

This utilizes cspell 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:

check-spelling:
    DO github.com/input-output-hk/catalyst-ci/earthly/cspell:<tag>+CHECK

Executing earthly +check-spelling will automatically run the spell checking to all files in the repository.

Configuration¶

Each repo will need a cspell.json 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:

<repo root>/.config/dictionaries/project.dic

The path can also be configured in the cspell.json file.

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

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

cspell: words <words>

Here are some examples for inlining:

Comments on Earthfiles

# cspell: words libgcc freetype lcms openjpeg etag

Comments on markdown files

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