diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 61cd5849..e6384701 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,7 @@ - [ ] The commit message follows our [guidelines](https://github.com/get-woke/woke/blob/main/CONTRIBUTING.md) - [ ] Tests for the changes have been added (for bug fixes / features) -- [ ] Docs have been added / updated (for bug fixes / features) +- [ ] Docs have been added / updated (for bug fixes / features) see [docs/README.md](https://github.com/get-woke/woke/blob/main/docs/README.md) **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 213d5785..869160db 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,14 +1,45 @@ -name: Documentation refresh +name: MkDocs page on: push: - tags: - - v* + branches: [ main ] + paths: + - "docs/**" + - mkdocs.yml + - .github/workflows/docs.yml + pull_request: + paths: + - "docs/**" + - mkdocs.yml + - .github/workflows/docs.yml jobs: - docs: - name: Renew documentation + mkdocs: runs-on: ubuntu-latest steps: - - name: Pull new module version - uses: andrewslotin/go-proxy-pull-action@v1.0.2 + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: 3.x + - run: pip install -r docs/requirements.txt + + - name: MkDocs build + if: github.event_name == 'pull_request' + run: mkdocs build + + - name: MkDocs deploy + if: github.event_name != 'pull_request' + run: | + # Hard-code user configuration + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config user.name "github-actions" + mkdocs gh-deploy --force + markdownlint: + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + steps: + - uses: actions/checkout@v2 + - uses: nosborn/github-action-markdown-cli@v2.0.0 + with: + files: docs/*.md + config_file: .markdownlint.json diff --git a/.github/workflows/go-docs.yml b/.github/workflows/go-docs.yml new file mode 100644 index 00000000..213d5785 --- /dev/null +++ b/.github/workflows/go-docs.yml @@ -0,0 +1,14 @@ +name: Documentation refresh + +on: + push: + tags: + - v* + +jobs: + docs: + name: Renew documentation + runs-on: ubuntu-latest + steps: + - name: Pull new module version + uses: andrewslotin/go-proxy-pull-action@v1.0.2 diff --git a/.gitignore b/.gitignore index e755a6bf..ece01973 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ dist/* # pprof files *.test *.prof + +# mkdocs +site/ diff --git a/.markdownlint.json b/.markdownlint.json index bb096f00..b219f10a 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -2,5 +2,6 @@ "line-length": false, "no-emphasis-as-heading": false, "no-inline-html": false, - "first-line-h1": false + "first-line-h1": false, + "no-duplicate-header": false } diff --git a/.wokeignore b/.wokeignore index 102aba62..60a67cc9 100644 --- a/.wokeignore +++ b/.wokeignore @@ -3,3 +3,4 @@ pkg/rule/default.yaml example.yaml README.md testdata +docs/*.md diff --git a/README.md b/README.md index 61955bd6..be2af707 100644 --- a/README.md +++ b/README.md @@ -36,439 +36,26 @@ Companies like [GitHub](https://github.com/github/renaming), [Twitter](https://t ![woke.gif](https://raw.githubusercontent.com/get-woke/get-woke.github.io/main/img/woke.gif) -**Table of Contents** +## Install `woke` -- [Installation](#installation) - - [macOS](#macos) - - [Windows](#windows) - - [Simple installation](#simple-installation) - - [Build from source](#build-from-source) - - [Releases](#releases) - - [Docker](#docker) -- [Usage](#usage) - - [File globs](#file-globs) - - [STDIN](#stdin) - - [Output](#output) - - [Rules](#rules) - - [Options](#options) - - [Disabling Default Rules](#disabling-default-rules) - - [Ignoring](#ignoring) - - [Files](#files) - - [`.wokeignore`](#wokeignore) - - [In-line ignoring](#in-line-ignoring) - - [Exit Code](#exit-code) - - [Parallelism](#parallelism) -- [Tools](#tools) -- [Who uses `woke`](#who-uses-woke) -- [Resources](#resources) -- [Contributing](#contributing) -- [Versioning](#versioning) -- [Authors](#authors) -- [Acknowledgments](#acknowledgments) -- [License](#license) +- [On my machine](https://docs.getwoke.tech/installation); +- [On CI/CD systems](https://docs.getwoke.tech/installation/#ci). -## Installation +## Documentation -### macOS - -You can install a binary release on macOS using [brew](https://brew.sh) - -```bash -brew install get-woke/tap/woke -brew upgrade get-woke/tap/woke -``` - -### Windows - -You can install `woke` with [`scoop`](https://scoop.sh/) - -```sh -scoop bucket add get-woke https://github.com/get-woke/scoop-bucket.git -scoop install get-woke/woke -``` - -### Simple installation - -To install the latest version: - -```bash -curl -sSfL https://git.io/getwoke | \ - bash -s -- -b /usr/local/bin -``` - -Or install a specific version (omit the minor or patch portion to install the latest major/minor version) - -```bash -curl -sSfL https://git.io/getwoke | \ - bash -s -- -b /usr/local/bin v0.9.0 -``` - -Feel free to change the path from `/usr/local/bin`, just make sure `woke` -is available on your `$PATH` (check with `woke --version`). - -### Build from source - -Install the go toolchain: - -```bash -go get -u github.com/get-woke/woke -``` - -`woke` will be installed to `$GOPATH/bin/woke`. - -### Releases - -Download the latest binary from [Releases](https://github.com/get-woke/woke/releases/latest) - -### Docker - -You can run `woke` within docker. You will need to mount a volume that contains your source code and/or rules. - -```bash -## Run with all defaults, within the mounted /src directory -docker run -v $(pwd):/src -w /src getwoke/woke - -## Provide rules config -docker run -v $(pwd):/src -w /src getwoke/woke \ - woke -c my-rules.yaml -``` - -## Usage - -```text -$ woke --help - -woke is a linter that will check your source code for usage of non-inclusive -language and provide suggestions for alternatives. Rules can be customized -to suit your needs. - -Provide a list file globs for files you'd like to check. - -Usage: - woke [globs ...] [flags] - -Flags: - -c, --config string Config file (default is .woke.yaml in current directory, or $HOME) - --debug Enable debug logging - --exit-1-on-failure Exit with exit code 1 on failures - -h, --help help for woke - --no-ignore Ignored files in .gitignore, .ignore, .wokeignore, .git/info/exclude, and inline ignores are processed - -o, --output string Output type [text,simple,github-actions,json,sonarqube] (default "text") - --stdin Read from stdin - -v, --version version for woke -``` - -### File globs - -By default, `woke` will run against all text files in your current directory. -To change this, supply a space-separated list of globs as the first argument. - -This can be something like `**/*.go`, or a space-separated list of filenames. - -```bash -$ woke test.txt -test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) -* Blacklist - ^ -test.txt:3:2-12: `White-list` may be insensitive, use `allowlist` instead (warning) -* White-list - ^ -test.txt:4:2-11: `whitelist` may be insensitive, use `allowlist` instead (warning) -* whitelist - ^ -test.txt:5:2-11: `blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) -* blacklist - ^ -``` - -### STDIN - -You can also provide text to `woke` via STDIN (Standard Input) - -```bash -$ echo "This has whitelist from stdin" | woke --stdin -/dev/stdin:1:9-18: `whitelist` may be insensitive, use `allowlist` instead (warning) -This has whitelist from stdin - ^ -``` - -This option may not be used at the same time as [File Globs](#file-globs) - -### Output - -Options for output include text (default), simple, json, github-actions, or sonarqube format. The following fields are supported, depending on format: - -| Field | Description | -| ------------ | ------------ | -| filepath | Relative path to file including filename | -| rulename | Name of the rule from the config file | -| termname | Specific term that was found in the text | -| alternative | List of alternative terms to use instead | -| note | Note about reasoning for inclusion | -| severity | From config, one of "error", "warning", or "info" | -| optionbool | Option value, true or false | -| linecontents | Contents of the line with finding | -| lineno | Line number, 1 based | -| startcol | Starting column number, 0 based | -| endcol | Ending column number, 0 based | -| description | Description of finding | - -Output is sent to STDOUT (Standard Output), which may be redirected to a file to save the results of a scan. - -#### text - -text is the default output format for woke. Displays each result on two lines. Includes color formatting if the terminal supports it. - -Structure: - -``` -::-: () - -``` - -#### simple - -simple is a format similar to text, but without color support and with each result on a single line. - -Structure: - -``` -::: -``` - -#### github-actions - -The github-actions output type is intended for integration with [GitHub Actions](https://github.com/features/actions). See [woke-action](https://github.com/get-woke/woke-action) for more information on integration. - -Structure: - -``` -:: file=,line=,col=:: -``` - -#### json - -Outputs the results as a series of [json](https://www.json.org/json-en.html) formatted structures, one per line. In order to parse as a JSON document, each line must be processed separately. This output type includes every field available in woke. - -Structure: - -``` -{"Filename":"","Results":[{"Rule":{"Name":"","Terms":["",...],"Alternatives":["",...],"Note":"","Severity":"","Options":{"WordBoundary":,"WordBoundaryStart":,"WordBoundaryEnd":,"IncludeNote":}},"Finding":"","Line":"","StartPosition":{"Filename":"","Offset":0,"Line":,"Column":},"EndPosition":{"Filename":"","Offset":0,"Line":,"Column":},"Reason":""}]} -``` - -#### sonarqube - -Format used to populate results into the popular [SonarQube](https://www.sonarqube.org/) code quality tool. Note: woke is not executed as part of SonarQube itself, so must be run and the results file output prior to execution. Typically woke would be executed with an automation server such as Jenkins, Travis CI or Github Actions prior to creating the SonarQube report. For details on the file format, see [Generic Issue Input Format](https://docs.sonarqube.org/latest/analysis/generic-issue/). The [Analysis Parameter](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) `sonar.externalIssuesReportPaths` is used to point to the path to the report file generated by woke. - -Structure: - -``` -{"issues":[{"engineId":"woke","ruleId":"","primaryLocation":{"message":"","filePath":"","textRange":{"startLine":,"startColumn":,"endColumn":}},"type":"CODE_SMELL","severity":""} -]} -``` - -_Note: sonarqubeseverity is mapped from severity, such that an error in woke is translated to a MAJOR, warning to a MINOR, and info to INFO_ - -### Rules - -Configure your custom rules config in `.woke.yaml` or `.woke.yml`. `woke` uses the following precedence order. Each item takes precedence over the item below it: - -- `current working directory` -- `$HOME` - -This file will be picked up automatically up your customizations without needing to supply it with the `-c` flag. - -See [example.yaml](https://github.com/get-woke/woke/blob/main/example.yaml) for an example of adding custom rules. -You can also supply your own rules with `-c path/to/rules.yaml` if you want to handle different rulesets. - -The syntax for rules is very basic. You just need a name, a list of terms to match that violate the rule, -and a list of alternative suggestions. - -```yaml -rules: - - name: whitelist - terms: - - whitelist - - white-list - alternatives: - - allowlist - note: An optional description why these terms are not inclusive. It can be optionally included in the output message. - # options: - # word_boundary: false - # word_boundary_start: false - # word_boundary_end: false - # include_note: false -``` - -A set of default rules is provided in [`pkg/rule/default.yaml`](https://github.com/get-woke/woke/blob/main/pkg/rule/default.yaml). - -**NOTE: if you copy these rules into your config file, be sure to put them under the `rules:` key.** - -#### Options - -You can configure options for each rule. Add an `options` key to your rule definition to customize. - -Current options include: - -- `word_boundary` (default: `false`) - - If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. - - **NOTE** setting this to true will always win out over `word_boundary_start` and `word_boundary_end` -- `word_boundary_start` (default: `false`) - - If `true`, terms will trigger findings when they begin with an ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. -- `word_boundary_end` (default: `false`) - - If `true`, terms will trigger findings when they end with an ASCII word boundaries. - - If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. -- `include_note` (default: `not set`) - - If `true`, the rule note will be included in the output message explaining why this finding is not inclusive - - If `false`, the rule note will not be included in the output message - - If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). - -#### Disabling Default Rules - -You can disable default rules by providing a rule in your `woke` config file (ie `.woke.yml`), with no terms or alternatives. - -This will disable the default `whitelist` rule: - -```yaml -rules: - - name: whitelist -``` - -### Ignoring - -#### Files - -You can ignore files by adding to your config file. All ways of ignoring files below should follow the [gitignore](https://git-scm.com/docs/gitignore) convention. - -```yaml -ignore_files: - - .git/* - - other/files/in/repo - - globs/too/* -``` - -`woke` will also automatically ignore anything listed in `.gitignore`, `.ignore`, and `.git/info/exclude`. - -#### `.wokeignore` - -You may also specify a `.wokeignore` file at the root of the directory to add additional ignore files. -This also follows the [gitignore](https://git-scm.com/docs/gitignore) convention. - -See [.wokeignore.example](.wokeignore.example) for a collection of common files and directories that may contain generated [SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms) and [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s. Dependency directories are also shown in the example as the linter will parse dependency source code and possibly find errors. - -#### In-line and next-line ignoring - -There may be times where you don't want to ignore an entire file. -You may ignore a specific line for one or more rules by creating an in-line or next-line comment. - -This functionality is very rudimentary, it does a simple search for the phrase. Since -`woke` is just a text file analyzer, it has no concept of the comment syntax for every file -type it might encounter. - -For in-line ignoring, simply add the following to the line you wish to ignore, using comment syntax that is supported for your file type. -(`woke` is not responsible for broken code due to in-line ignoring. Make sure you comment correctly!) - -Next-line ignoring works in a similar way. Instead of adding to the end of line you wish to ignore, you can create the ignore comment on its own line just before it. Any alphanumeric text to the left of the phrase will cause `woke` to treat it as an in-line ignore, but any text to the right of the phrase will not be considered. -(Note: next-line ignore comments takes precedence over in-line ignores, so try to only use one for any given line!) - -```bash -This line has RULE_NAME but will be ignored # wokeignore:rule=RULE_NAME - -# wokeignore:rule=RULENAME -Here is another line with RULE_NAME that will be ignored - -# a couple of examples ignoring the following line for the whitelist rule -whitelist # wokeignore:rule=whitelist - -# wokeignore:rule=whitelist -whitelist - -# a couple of examples doing the same for multiple rules -# rule names must be comma-separated with no spaces -whitelist and blacklist # wokeignore:rule=whitelist,blacklist - -# wokeignore:rule=whitelist,blacklist -whitelist and blacklist - -# wokeignore:rule=whitelist text here won't be considered by woke even if it contains whitelist -this line with whitelist will still be ignored -``` - -Here's an example in go: - -```go -func main() { - fmt.Println("here is the whitelist") // wokeignore:rule=whitelist - - // wokeignore:rule=blacklist - fmt.Println("and here is the blacklist") -} -``` - -### Exit Code - -By default, `woke` will exit with a successful exit code when there are any rule failures. -The idea is, if you run `woke` on PRs, you may not want to block a merge, but you do -want to inform the author that they can make better word choices. - -If you're using `woke` on PRs, you can choose to enforce these rules with a non-zero -exit code by running `woke --exit-1-on-failure`. - -### Parallelism - -By default, `woke` will parse files in parallel and will consume as many resources as it can, unbounded. -This means `woke` will be fast, but might run out of memory, depending on how large the files/lines are. - -We can limit these allocations by bounding the number of files read in parallel. To accomplish this, -set the environment variable `WORKER_POOL_COUNT` to an integer value of the fixed number of goroutines -you would like to spawn for reading files. - -Read more about go's concurrency patterns [here](https://blog.golang.org/pipelines). - -## Tools - -- [GitHub Action](https://github.com/marketplace/actions/run-woke) -- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) -- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=get-woke.vscode-woke) - -## Who uses `woke` - -Are you using `woke` in your org? We'd love to know! Please send a PR and add your organization name/link to this list. - -- [Rent the Runway](https://www.renttherunway.com) ([blog post](https://dresscode.renttherunway.com/blog/woke)) -- [Veue](https://veuelive.com) -- [Cisco](https://ciscotechblog.com/blog/inclusive-infrastructure/) - -## Resources - -- -- -- -- +Documentation is hosted at . ## Contributing Please read [CONTRIBUTING.md](https://github.com/get-woke/woke/blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. -## Versioning - -We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/get-woke/woke/tags). +![GitHub contributors](https://img.shields.io/github/contributors/get-woke/woke) ## Authors - **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) - - -## Acknowledgments - -The following projects provided inspiration for parts of `woke` - -- -- -- +See also the list of [contributors](https://github.com/get-woke/woke/contributors) who have participated in this project. ## License diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..3f2fb833 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +docs.getwoke.tech diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 00000000..c2bb2a22 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,9 @@ +FROM python:3-alpine + +WORKDIR /workdir +COPY docs/requirements.txt /workdir +RUN pip install -r /workdir/requirements.txt + +EXPOSE 8000 + +CMD ["mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"] diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..cd0e449e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# Woke documentation site + +Woke uses the [material](https://squidfunk.github.io/mkdocs-material/) MkDocs theme. + +You can find the live site at . + +See [mkdocs.yml](../mkdocs.yml) for details. + +## Running locally + +```bash +docker build -t woke-mkdocs -f docs/Dockerfile . +docker run --rm -v `pwd`:/workdir -w /workdir -p 8000:8000 woke-mkdocs +``` + +You can now access the site locally via `http://localhost:8000`. Auto-reload is enabled + +## Deploying + +Any changes made to the `docs` directory will be automatically deployed on merges to `main`. diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..4e6d23f7 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,45 @@ +# About + +## Resources + +Below are some additional resources relating to why this project is important. + +- +- +- +- + +## Who uses `woke`? + +Are you using `woke` in your org? We'd love to know! Please send a PR and add your organization name/link to this list. + +- [Rent the Runway](https://www.renttherunway.com) ([blog post](https://dresscode.renttherunway.com/blog/woke)) +- [Veue](https://veuelive.com) +- [Cisco](https://ciscotechblog.com/blog/inclusive-infrastructure/) + +## Contributing + +Please read [CONTRIBUTING.md]({{config.repo_url}}blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/get-woke/woke/tags). + +## Authors + +- **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) + + + +## Acknowledgments + +The following projects provided inspiration for parts of `woke` + +- +- +- + +## License + +This application is licensed under the MIT License, you may obtain a copy of it +[here]({{config.repo_url}}blob/main/LICENSE). diff --git a/docs/assets/default-monochrome.svg b/docs/assets/default-monochrome.svg new file mode 100644 index 00000000..46d82d3b --- /dev/null +++ b/docs/assets/default-monochrome.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 00000000..336e3809 Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 00000000..041392df --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,3 @@ +[data-md-color-scheme="woke"] { + --md-accent-fg-color: #D1A103; +} diff --git a/docs/ignore.md b/docs/ignore.md new file mode 100644 index 00000000..8cd66056 --- /dev/null +++ b/docs/ignore.md @@ -0,0 +1,76 @@ +# Ignoring + +## Files + +You can ignore files by adding to your config file. All ways of ignoring files below should follow the [gitignore](https://git-scm.com/docs/gitignore) convention. + +```yaml +ignore_files: + - other/files/in/repo + - globs/too/* +``` + +!!! note "`.git`" + Woke will always ignore the `.git` directory so there's no need to include it in any of the ignore configurations. + +`woke` will also automatically ignore anything listed in `.gitignore`, `.ignore`, and `.git/info/exclude`. + +## `.wokeignore` + +You may also specify a `.wokeignore` file at the root of the directory to add additional ignore files. +This also follows the [gitignore](https://git-scm.com/docs/gitignore) convention. + +See [.wokeignore.example]({{config.repo_url}}blob/main/.wokeignore.example) for a collection of common files and directories that may contain generated [SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms) and [GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)s. Dependency directories are also shown in the example as the linter will parse dependency source code and possibly find errors. + +## In-line and next-line ignoring + +There may be times where you don't want to ignore an entire file. +You may ignore a specific line for one or more rules by creating an in-line or next-line comment. + +This functionality is very rudimentary, it does a simple search for the phrase. Since +`woke` is just a text file analyzer, it has no concept of the comment syntax for every file +type it might encounter. + +For in-line ignoring, simply add the following to the line you wish to ignore, using comment syntax that is supported for your file type. + +!!! danger + `woke` is not responsible for broken code due to in-line ignoring. Make sure you comment correctly! + +Next-line ignoring works in a similar way. Instead of adding to the end of line you wish to ignore, you can create the ignore comment on its own line just before it. Any alphanumeric text to the left of the phrase will cause `woke` to treat it as an in-line ignore, but any text to the right of the phrase will not be considered. + +!!! note + Next-line ignore comments takes precedence over in-line ignores, so try to only use one for any given line! + +```bash +This line has RULE_NAME but will be ignored # wokeignore:rule=RULE_NAME + +# wokeignore:rule=RULENAME +Here is another line with RULE_NAME that will be ignored + +# a couple of examples ignoring the following line for the whitelist rule +whitelist # wokeignore:rule=whitelist + +# wokeignore:rule=whitelist +whitelist + +# a couple of examples doing the same for multiple rules +# rule names must be comma-separated with no spaces +whitelist and blacklist # wokeignore:rule=whitelist,blacklist + +# wokeignore:rule=whitelist,blacklist +whitelist and blacklist + +# wokeignore:rule=whitelist text here won't be considered by woke even if it contains whitelist +this line with whitelist will still be ignored +``` + +Here's an example in go: + +```go +func main() { + fmt.Println("here is the whitelist") // wokeignore:rule=whitelist + + // wokeignore:rule=blacklist + fmt.Println("and here is the blacklist") +} +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..8afd37e6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,47 @@ +# + +

+woke logo +

{{ config.site_description }}

+

+ + +[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/get-woke/woke?logo=github&sort=semver)]({{config.repo_url}}releases) +[![GitHub All Releases](https://img.shields.io/github/downloads/get-woke/woke/total)]({{config.repo_url}}releases) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)]({{config.repo_url}}blob/main/LICENSE) +[![codecov](https://codecov.io/gh/get-woke/woke/branch/main/graph/badge.svg?token=BP133BM3HP)](https://codecov.io/gh/get-woke/woke/branch/main) +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fget-woke%2Fwoke.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fget-woke%2Fwoke?ref=badge_shield) +[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#other-software) + +--- + +## About + +Creating an inclusive work environment is imperative to a healthy, supportive, and +productive culture, and an environment where everyone feels welcome and included. + +`woke` is a text file analysis tool that finds places within your source code that contain +non-inclusive language and suggests replacing them with more inclusive alternatives. + +Companies like [GitHub](https://github.com/github/renaming), [Twitter](https://twitter.com/TwitterEng/status/1278733303508418560), and [Apple](https://developer.apple.com/news/?id=1o9zxsxl) are actively supporting a move to inclusive language. + +## Demo + +![woke.gif](https://raw.githubusercontent.com/get-woke/get-woke.github.io/main/img/woke.gif) + +## Authors + +- **Caitlin Elfring** - [caitlinelfring](https://github.com/caitlinelfring) + +See also the list of [contributors]({{config.repo_url}}contributors) who participated in this project. + +## Contributing + +Please read [CONTRIBUTING.md]({{config.repo_url}}blob/main/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. + +## License + +This application is licensed under the MIT License, you may obtain a copy of it +[here]({{config.repo_url}}blob/main/LICENSE). + +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fget-woke%2Fwoke.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fget-woke%2Fwoke?ref=badge_large) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..2b600b44 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,80 @@ +# Installation + +!!! tip + There are multiple ways to install `woke`. If you're interested in any installation methods + that are not listed here, feel free to open an [issue]({{config.repo_url}}issues). + +## Releases + +Download the latest binary from [Releases]({{config.repo_url}}releases/latest) + +## macOS + +You can install a binary release on macOS using [brew](https://brew.sh) + +```bash +brew install get-woke/tap/woke +brew upgrade get-woke/tap/woke +``` + +## Windows + +You can install `woke` with [`scoop`](https://scoop.sh/) + +```sh +scoop bucket add get-woke https://github.com/get-woke/scoop-bucket.git +scoop install get-woke/woke +``` + +## Simple installation + +To install the latest version: + +```bash +curl -sSfL https://git.io/getwoke | \ + bash -s -- -b /usr/local/bin +``` + +Or install a specific version (omit the minor or patch portion to install the latest major/minor version) + +```bash +curl -sSfL https://git.io/getwoke | \ + bash -s -- -b /usr/local/bin v0.9.0 +``` + +Feel free to change the path from `/usr/local/bin`, just make sure `woke` +is available on your `$PATH` (check with `woke --version`). + +## Build from source + +Install the go toolchain: + +```bash +go get -u github.com/get-woke/woke +``` + +`woke` will be installed to `$GOPATH/bin/woke`. + +## Docker + +You can run `woke` within docker. You will need to mount a volume that contains your source code and/or rules. + +```bash +## Run with all defaults, within the mounted /src directory +docker run -v $(pwd):/src -w /src getwoke/woke + +## Provide rules config +docker run -v $(pwd):/src -w /src getwoke/woke \ + woke -c my-rules.yaml +``` + +## CI + +### GitHub Actions + +- [GitHub Action](https://github.com/marketplace/actions/run-woke) +- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) + +### Others + +Are there other CI systems that you're using to run `woke`? Edit this page and add documentation/configurations for others. diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..02d156a4 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,23 @@ +{% extends "base.html" %} + +{% block extrahead %} + {% set title = config.site_name %} + {% if page and page.meta and page.meta.title %} + {% set title = title ~ " - " ~ page.meta.title %} + {% elif page and page.title and not page.is_homepage %} + {% set title = title ~ " - " ~ page.title | striptags %} + {% endif %} + + + + + + + + + + + + + +{% endblock %} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c1c9c81d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,9 @@ +# python requirements for docs +# https://www.mkdocs.org/ +# https://squidfunk.github.io/mkdocs-material/ +mkdocs +mkdocs-material +fontawesome-markdown +markdown-include +pymdown-extensions +mkdocs-macros-plugin diff --git a/docs/rules.md b/docs/rules.md new file mode 100644 index 00000000..70aca199 --- /dev/null +++ b/docs/rules.md @@ -0,0 +1,72 @@ +# Rules + +## Schema + +The syntax for rules is very basic. You just need a name, a list of terms to match that violate the rule, +and a list of alternative suggestions. + +```yaml +rules: + - name: whitelist + terms: + - whitelist + - white-list + alternatives: + - allowlist + note: An optional description why these terms are not inclusive. It can be optionally included in the output message. + # options: + # word_boundary: false + # word_boundary_start: false + # word_boundary_end: false + # include_note: false +``` + +A set of default rules is provided in [`pkg/rule/default.yaml`]({{config.repo_url}}blob/main/pkg/rule/default.yaml). + +!!! tip + If you copy these rules into your config file, be sure to put them under the `rules:` key. + +## Options + +You can configure options for each rule. Add an `options` key to your rule definition to customize. + +### `word_boundary` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they are surrounded by ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it is within an ASCII word boundary. +* !!! warning "setting `word_boundary` to `true` will always win out over `word_boundary_start` and `word_boundary_end`" + +### `word_boundary_start` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they begin with an ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it begins with an ASCII word boundary. + +### `word_boundary_end` + +:octicons-milestone-24: Default: `false` + +* If `true`, terms will trigger findings when they end with an ASCII word boundaries. +* If `false`, will trigger findings if the term if found anywhere in the line, regardless if it ends with an ASCII word boundary. + +### `include_note` + +:octicons-milestone-24: Default: `not set` + +* If `true`, the rule note will be included in the output message explaining why this finding is not inclusive +* If `false`, the rule note will not be included in the output message +* If `not set`, `include_note` in your `woke` config file (ie `.woke.yml`) regulates if the note should be included in the output message (default: `false`). + +## Disabling Default Rules + +You can disable default rules by providing a rule in your `woke` config file (ie `.woke.yml`), with no terms or alternatives. + +This will disable the default `whitelist` rule: + +```yaml +rules: + - name: whitelist +``` diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 00000000..c0828d0f --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,6 @@ +# Tools + +- [GitHub Action](https://github.com/marketplace/actions/run-woke) +- [GitHub Action (reviewdog)](https://github.com/marketplace/actions/run-woke-with-reviewdog) +- [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=get-woke.vscode-woke) +- [VIM Plugin](https://github.com/get-woke/vim-woke) diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..7a0824bd --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,254 @@ +# Usage + +```text +$ woke --help + +woke is a linter that will check your source code for usage of non-inclusive +language and provide suggestions for alternatives. Rules can be customized +to suit your needs. + +Provide a list file globs for files you'd like to check. + +Usage: + woke [globs ...] [flags] + +Flags: + -c, --config string Config file (default is .woke.yaml in current directory, or $HOME) + --debug Enable debug logging + --exit-1-on-failure Exit with exit code 1 on failures + -h, --help help for woke + --no-ignore Ignored files in .gitignore, .ignore, .wokeignore, .git/info/exclude, and inline ignores are processed + -o, --output string Output type [text,simple,github-actions,json,sonarqube] (default "text") + --stdin Read from stdin + -v, --version version for woke +``` + +## Config file + +Configure your custom rules config in `.woke.yaml` or `.woke.yml`. `woke` uses the following precedence order. Each item takes precedence over the item below it: + +- `current working directory` +- `$HOME` + +This file will be picked up automatically up your customizations without needing to supply it with the `-c` flag. + +See [example.yaml]({{config.repo_url}}blob/main/example.yaml) for an example of adding custom rules. +You can also supply your own rules with `-c path/to/rules.yaml` if you want to handle different rulesets. + +## Inputs + +### File globs + +By default, `woke` will run against all text files in your current directory. +To change this, supply a space-separated list of globs as the first argument. + +This can be something like `**/*.go`, or a space-separated list of filenames. + +```bash +$ woke test.txt +test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) +* Blacklist + ^ +test.txt:3:2-12: `White-list` may be insensitive, use `allowlist` instead (warning) +* White-list + ^ +test.txt:4:2-11: `whitelist` may be insensitive, use `allowlist` instead (warning) +* whitelist + ^ +test.txt:5:2-11: `blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) +* blacklist + ^ +``` + +### STDIN + +You can also provide text to `woke` via STDIN (Standard Input) + +```bash +$ echo "This has whitelist from stdin" | woke --stdin +/dev/stdin:1:9-18: `whitelist` may be insensitive, use `allowlist` instead (warning) +This has whitelist from stdin + ^ +``` + +This option may not be used at the same time as [File Globs](#file-globs) + +## Outputs + +Options for output include text (default), simple, json, github-actions, or sonarqube format. +The following fields are supported, depending on format: + +| Field | Description | +| ------------ | ------------ | +| filepath | Relative path to file including filename | +| rulename | Name of the rule from the config file | +| termname | Specific term that was found in the text | +| alternative | List of alternative terms to use instead | +| note | Note about reasoning for inclusion | +| severity | From config, one of "error", "warning", or "info" | +| optionbool | Option value, true or false | +| linecontents | Contents of the line with finding | +| lineno | Line number, 1 based | +| startcol | Starting column number, 0 based | +| endcol | Ending column number, 0 based | +| description | Description of finding | + +Output is sent to STDOUT (Standard Output), which may be redirected to a file to save the results of a scan. + +### Text + +!!! example "" + `woke -o text` + +`text` is the default output format for woke. Displays each result on two lines. Includes color formatting if the terminal supports it. + +#### Structure + +```text +::-: () + +``` + +### Simple + +!!! example "" + `woke -o simple` + +`simple` is a format similar to text, but without color support and with each result on a single line. + +#### Structure + +```text +::: +``` + +### GitHub Actions + +!!! example "" + `woke -o github-actions` + +The `github-actions` output type is intended for integration with [GitHub Actions](https://github.com/features/actions). See [woke-action](https://github.com/get-woke/woke-action) for more information on integration. + +#### Structure + +```text +:: file=,line=,col=:: +``` + +### JSON + +!!! example "" + `woke -o json` + +Outputs the results as a series of [`json`](https://www.json.org/json-en.html) formatted structures, one per line. In order to parse as a JSON document, each line must be processed separately. This output type includes every field available in woke. + +#### Structure + +!!! info inline end + Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. + +```json +{ + "Filename": "", + "Results": [ + { + "Rule": { + "Name": "", + "Terms": [ + "", + ... + ], + "Alternatives": [ + "", + ... + ], + "Note": "", + "Severity": "", + "Options": { + "WordBoundary": , + "WordBoundaryStart": , + "WordBoundaryEnd": , + "IncludeNote": + } + }, + "Finding": "", + "Line": "", + "StartPosition": { + "Filename": "", + "Offset": 0, + "Line": , + "Column": + }, + "EndPosition": { + "Filename": "", + "Offset": 0, + "Line": , + "Column": + }, + "Reason": "" + } + ] +} +``` + +### SonarQube + +!!! example "" + `woke -o sonarqube` + +Format used to populate results into the popular [SonarQube](https://www.sonarqube.org/) code quality tool. Note: `woke` is not executed as part of SonarQube itself, so must be run and the results file output prior to execution. Typically woke would be executed with an automation server such as Jenkins, Travis CI or Github Actions prior to creating the SonarQube report. For details on the file format, see [Generic Issue Input Format](https://docs.sonarqube.org/latest/analysis/generic-issue/). The [Analysis Parameter](https://docs.sonarqube.org/latest/analysis/analysis-parameters/) `sonar.externalIssuesReportPaths` is used to point to the path to the report file generated by `woke`. + +#### Structure + +!!! info inline end + Actual output from woke will be consolidated JSON. Pretty-JSON here is just for readability. + +```json +{ + "issues": [ + { + "engineId": "woke", + "ruleId": "", + "primaryLocation": { + "message": "", + "filePath": "", + "textRange": { + "startLine": , + "startColumn": , + "endColumn": + } + }, + "type": "CODE_SMELL", + "severity": "" + } + ] +} +``` + +!!! note + `` is mapped from severity, such that an error in `woke` is translated to a `MAJOR`, warning to a `MINOR`, and info to `INFO` + +## Exit Code + +By default, `woke` will exit with a successful exit code when there are any rule failures. +The idea is, if you run `woke` on PRs, you may not want to block a merge, but you do +want to inform the author that they can make better word choices. + +If you're using `woke` on PRs, you can choose to enforce these rules with a non-zero +exit code by running `woke --exit-1-on-failure`. + +## Parallelism + +!!! error "Advanced Configuration" + It's unlikely that you will need to adjust parallelism. But in case you do, if you are running `woke` + with limited resources, and/or against a very large directory, you may want to restrict the number of + threads that `woke` uses. + +By default, `woke` will parse files in parallel and will consume as many resources as it can, unbounded. +This means `woke` will be fast, but might run out of memory, depending on how large the files/lines are. + +We can limit these allocations by bounding the number of files read in parallel. To accomplish this, +set the environment variable `WORKER_POOL_COUNT` to an integer value of the fixed number of goroutines +you would like to spawn for reading files. + +Read more about go's concurrency patterns [here](https://blog.golang.org/pipelines). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..872c41f8 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,96 @@ +site_name: "Woke - Detect non-inclusive language in your source code" + +site_author: Caitlin Elfring +site_description: Detect non-inclusive language in your source code. +theme: + name: material + custom_dir: docs/overrides + logo: assets/default-monochrome.svg + favicon: assets/favicon.ico + palette: + scheme: woke + primary: black + icon: + repo: fontawesome/brands/github + features: + - navigation.instant + - navigation.tabs + - navigation.tracking + - navigation.sections + - navigation.expand + - navigation.top + - toc.integrate + - search.suggest + - search.highlight +nav: + - Introduction: index.md + - Getting Started: + - Installation: installation.md + - User Guide: + - Usage: usage.md + - Rules: rules.md + - Ignoring: ignore.md + - More Info: + About: about.md + Tools: tools.md + +markdown_extensions: + - admonition + - abbr + - attr_list + - def_list + - footnotes + - meta + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tabbed + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + +plugins: + - macros + - search + +repo_url: https://github.com/get-woke/woke +repo_name: get-woke/woke +edit_uri: edit/main/docs/ + +copyright: Copyright © 2020 - 2021 Caitlin Elfring + +extra_css: + - css/extra.css +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/get-woke + name: GitHub + - icon: fontawesome/brands/docker + link: https://hub.docker.com/r/getwoke/woke/ + name: Docker + # TODO + # analytics: + # provider: google + # property: G-XXXXXXXXXX + # property: UA-XXXXXXXX-X diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh index a9098549..8ba9e546 100755 --- a/scripts/pre-commit.sh +++ b/scripts/pre-commit.sh @@ -3,7 +3,7 @@ set -e if ! type woke > /dev/null; then - echo "woke is not installed, or is not available in your PATH. See https://github.com/get-woke/woke#installation." + echo "woke is not installed, or is not available in your PATH. See https://docs.getwoke.tech/installation." exit 1 fi