.pytool/Plugin: Add CI plugins
https://bugzilla.tianocore.org/show_bug.cgi?id=2315 Add .pytool directory to the edk2 repository with the following plugins. These plugins are in a top level directory because that can be used with all packages and platforms. * CharEncodingCheck * CompilerPlugin * DependencyCheck * DscCompleteCheck * GuidCheck * LibraryClassCheck * SpellCheck Cc: Sean Brogan <sean.brogan@microsoft.com> Cc: Bret Barkelew <Bret.Barkelew@microsoft.com> Cc: Liming Gao <liming.gao@intel.com> Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
This commit is contained in:
committed by
Michael D Kinney
parent
de4ce46d6e
commit
9da7846c88
127
.pytool/Plugin/SpellCheck/Readme.md
Normal file
127
.pytool/Plugin/SpellCheck/Readme.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Spell Check Plugin
|
||||
|
||||
This CiBuildPlugin scans all the files in a given package and checks for
|
||||
spelling errors.
|
||||
|
||||
This plugin requires NodeJs and cspell. If the plugin doesn't find its required
|
||||
tools then it will mark the test as skipped.
|
||||
|
||||
* NodeJS: https://nodejs.org/en/
|
||||
* cspell: https://www.npmjs.com/package/cspell
|
||||
* Src and doc available: https://github.com/streetsidesoftware/cspell
|
||||
|
||||
## Configuration
|
||||
|
||||
The plugin has a few configuration options to support the UEFI codebase.
|
||||
|
||||
``` yaml
|
||||
"SpellCheck": {
|
||||
"AuditOnly": False, # If True, log all errors and then mark as skipped
|
||||
"IgnoreFiles": [], # use gitignore syntax to ignore errors in matching files
|
||||
"ExtendWords": [], # words to extend to the dictionary for this package
|
||||
"IgnoreStandardPaths": [], # Standard Plugin defined paths that should be ignore
|
||||
"AdditionalIncludePaths": [] # Additional paths to spell check (wildcards supported)
|
||||
}
|
||||
```
|
||||
|
||||
### AuditOnly
|
||||
|
||||
Boolean - Default is False.
|
||||
If True run the test in an Audit only mode which will log all errors but instead
|
||||
of failing the build it will set the test as skipped. This allows visibility
|
||||
into the failures without breaking the build.
|
||||
|
||||
### IgnoreFiles
|
||||
|
||||
This supports .gitignore file and folder matching strings including wildcards
|
||||
|
||||
* All files will be parsed regardless but then any spelling errors found within
|
||||
ignored files will not be reported as an error.
|
||||
* Errors in ignored files will still be output to the test results as
|
||||
informational comments.
|
||||
|
||||
### ExtendWords
|
||||
|
||||
This list allows words to be added to the dictionary for the spell checker when
|
||||
this package is tested. These follow the rules of the cspell config words field.
|
||||
|
||||
### IgnoreStandardPaths
|
||||
|
||||
This plugin by default will check the below standard paths. If the package
|
||||
would like to ignore any of them list that here.
|
||||
|
||||
```python
|
||||
[
|
||||
# C source
|
||||
"*.c",
|
||||
"*.h",
|
||||
|
||||
# Assembly files
|
||||
"*.nasm",
|
||||
"*.asm",
|
||||
"*.masm",
|
||||
"*.s",
|
||||
|
||||
# ACPI source language
|
||||
"*.asl",
|
||||
|
||||
# Edk2 build files
|
||||
"*.dsc", "*.dec", "*.fdf", "*.inf",
|
||||
|
||||
# Documentation files
|
||||
"*.md", "*.txt"
|
||||
]
|
||||
```
|
||||
|
||||
### AdditionalIncludePaths
|
||||
|
||||
If the package would to add additional path patterns to be included in
|
||||
spellchecking they can be defined here.
|
||||
|
||||
## Other configuration
|
||||
|
||||
In the cspell.base.json there are numerous other settings configured. There is
|
||||
no support to override these on a per package basis but future features could
|
||||
make this available. One interesting configuration option is `minWordLength`.
|
||||
Currently it is set to _5_ which means all 2,3, and 4 letter words will be
|
||||
ignored. This helps minimize the number of technical acronyms, register names,
|
||||
and other UEFI specific values that must be ignored.
|
||||
|
||||
## False positives
|
||||
|
||||
The cspell dictionary is not perfect and there are cases where technical words
|
||||
or acronyms are not found in the dictionary. There are three ways to resolve
|
||||
false positives and the choice for which method should be based on how broadly
|
||||
the word should be accepted.
|
||||
|
||||
### CSpell Base Config file
|
||||
|
||||
If the change should apply to all UEFI code and documentation then it should be
|
||||
added to the base config file `words` section. The base config file is adjacent
|
||||
to this file and titled `cspell.base.json`. This is a list of accepted words
|
||||
for all spell checking operations on all packages.
|
||||
|
||||
### Package Config
|
||||
|
||||
In the package `*.ci.yaml` file there is a `SpellCheck` config section. This
|
||||
section allows files to be ignored as well as words that should be considered
|
||||
valid for all files within this package. Add the desired words to the
|
||||
"ExtendedWords" member.
|
||||
|
||||
### In-line File
|
||||
|
||||
CSpell supports numerous methods to annotate your files to ignore words,
|
||||
sections, etc. This can be found in CSpell documentation. Suggestion here is
|
||||
to use a c-style comment at the top of the file to add words that should be
|
||||
ignored just for this file. Obviously this has the highest maintenance cost so
|
||||
it should only be used for file unique words.
|
||||
|
||||
``` c
|
||||
// spell-checker:ignore unenroll, word2, word3
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```ini
|
||||
# spell-checker:ignore unenroll, word2, word3
|
||||
```
|
Reference in New Issue
Block a user