1# Spell Check Plugin
2
3This CiBuildPlugin scans all the files in a given package and checks for
4spelling errors.
5
6This plugin requires NodeJs and cspell.  If the plugin doesn't find its required
7tools then it will mark the test as skipped.
8
9* NodeJS: https://nodejs.org/en/
10* cspell: https://www.npmjs.com/package/cspell
11  * Src and doc available: https://github.com/streetsidesoftware/cspell
12
13## Configuration
14
15The plugin has a few configuration options to support the UEFI codebase.
16
17``` yaml
18  "SpellCheck": {
19      "AuditOnly": False,          # If True, log all errors and then mark as skipped
20      "IgnoreFiles": [],           # use gitignore syntax to ignore errors in matching files
21      "ExtendWords": [],           # words to extend to the dictionary for this package
22      "IgnoreStandardPaths": [],   # Standard Plugin defined paths that should be ignore
23      "AdditionalIncludePaths": [] # Additional paths to spell check (wildcards supported)
24  }
25```
26
27### AuditOnly
28
29Boolean - Default is False.
30If True run the test in an Audit only mode which will log all errors but instead
31of failing the build it will set the test as skipped.  This allows visibility
32into the failures without breaking the build.
33
34### IgnoreFiles
35
36This supports .gitignore file and folder matching strings including wildcards
37
38* All files will be parsed regardless but then any spelling errors found within
39  ignored files will not be reported as an error.
40* Errors in ignored files will still be output to the test results as
41  informational comments.
42
43### ExtendWords
44
45This list allows words to be added to the dictionary for the spell checker when
46this package is tested.  These follow the rules of the cspell config words field.
47
48### IgnoreStandardPaths
49
50This plugin by default will check the below standard paths.  If the package
51would like to ignore any of them list that here.
52
53```python
54[
55# C source
56"*.c",
57"*.h",
58
59# Assembly files
60"*.nasm",
61"*.asm",
62"*.masm",
63"*.s",
64
65# ACPI source language
66"*.asl",
67
68# Edk2 build files
69"*.dsc", "*.dec", "*.fdf", "*.inf",
70
71# Documentation files
72"*.md", "*.txt"
73]
74```
75
76### AdditionalIncludePaths
77
78If the package would to add additional path patterns to be included in
79spellchecking they can be defined here.
80
81## Other configuration
82
83In the cspell.base.json there are numerous other settings configured.  There is
84no support to override these on a per package basis but future features could
85make this available.  One interesting configuration option is `minWordLength`.
86Currently it is set to _5_ which means all 2,3, and 4 letter words will be
87ignored.  This helps minimize the number of technical acronyms, register names,
88and other UEFI specific values that must be ignored.
89
90## False positives
91
92The cspell dictionary is not perfect and there are cases where technical words
93or acronyms are not found in the dictionary.  There are three ways to resolve
94false positives and the choice for which method should be based on how broadly
95the word should be accepted.
96
97### CSpell Base Config file
98
99If the change should apply to all UEFI code and documentation then it should be
100added to the base config file `words` section.  The base config file is adjacent
101to this file and titled `cspell.base.json`.  This is a list of accepted words
102for all spell checking operations on all packages.
103
104### Package Config
105
106In the package `*.ci.yaml` file there is a `SpellCheck` config section.  This
107section allows files to be ignored as well as words that should be considered
108valid for all files within this package.  Add the desired words to the
109"ExtendedWords" member.
110
111### In-line File
112
113CSpell supports numerous methods to annotate your files to ignore words,
114sections, etc.  This can be found in CSpell documentation.  Suggestion here is
115to use a c-style comment at the top of the file to add words that should be
116ignored just for this file.  Obviously this has the highest maintenance cost so
117it should only be used for file unique words.
118
119``` c
120// spell-checker:ignore unenroll, word2, word3
121```
122
123or
124
125```ini
126# spell-checker:ignore unenroll, word2, word3
127```
128