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