diff --git a/.github/styles/AsciiDoc/ClosedAttributeBlocks.yml b/.github/styles/AsciiDoc/ClosedAttributeBlocks.yml new file mode 100644 index 00000000..b3e65fc5 --- /dev/null +++ b/.github/styles/AsciiDoc/ClosedAttributeBlocks.yml @@ -0,0 +1,7 @@ +--- +extends: existence +scope: raw +level: error +message: "Attribute block is not closed." +raw: + - '(?" + callout_regex := "^<(\\.)>" + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(codeblock_callout_regex, line) { + //restart for new listingblock + num_callouts = 0 + //account for lines with multiple callouts + num_callouts_in_line := text.count(line, "<.>") + if num_callouts_in_line > 1 { + num_codeblock_callouts = num_codeblock_callouts + num_callouts_in_line + } else { + num_codeblock_callouts++ + } + } + + if text.re_match(callout_regex, line) { + num_callouts++ + if num_callouts > num_codeblock_callouts { + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } + if num_callouts == num_codeblock_callouts { + num_callouts = 0 + num_codeblock_callouts = 0 + } + } + } diff --git a/.github/styles/AsciiDoc/MatchingNumberedCallouts.yml b/.github/styles/AsciiDoc/MatchingNumberedCallouts.yml new file mode 100644 index 00000000..7e2c6f1a --- /dev/null +++ b/.github/styles/AsciiDoc/MatchingNumberedCallouts.yml @@ -0,0 +1,62 @@ +--- +extends: script +message: "Corresponding callout not found." +level: warning +link: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + codeblock_callout_regex := ".+(<\\d+>)+" + callout_regex := "^<(\\d+)>" + codeblock_callouts := [] + inside := false + found := false + num_callouts := 0 + + num_lines := len(text.split(scope, "\n")) + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(codeblock_callout_regex, line) { + inside = true + //account for lines with multiple callouts + for i := 1; i < num_lines; i++ { + //text.contains must be str, not regex + str := "<" + i + ">" + if text.contains(line, str) { + codeblock_callouts = append(codeblock_callouts, i) + } + } + } else if text.re_match(callout_regex, line) { + inside = false + found = false + num_callouts = 1 + for i in codeblock_callouts { + //cast int > string + j := text.itoa(i) + str := "<" + j + ">" + if text.contains(line, str) { + //setting found allows us to loop through the list of possible matches + found = true + } + num_callouts++ + } + if !found { + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } + } else if codeblock_callouts && inside == false { + //cycled through num_callouts, reset for next codeblock + if num_callouts == len(codeblock_callouts) { + codeblock_callouts = [] + } + } + } \ No newline at end of file diff --git a/.github/styles/AsciiDoc/SequentialNumberedCallouts.yml b/.github/styles/AsciiDoc/SequentialNumberedCallouts.yml new file mode 100644 index 00000000..0a195f59 --- /dev/null +++ b/.github/styles/AsciiDoc/SequentialNumberedCallouts.yml @@ -0,0 +1,59 @@ +--- +extends: script +message: "Numbered callout does not follow sequentially." +level: warning +link: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + prev_num := 0 + callout_regex := "^<(\\d+)>" + listingblock_delim_regex := "^-{4,}$" + if_regex := "^ifdef::|ifndef::" + endif_regex := "^endif::\\[\\]" + inside_if := false + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + + // check if we're entering a conditional block + if text.re_match(if_regex, line) { + inside_if = true + } else if text.re_match(endif_regex, line) { + inside_if = false + } + + //reset count if we hit a listing block delimiter + if text.re_match(listingblock_delim_regex, line) { + prev_num = 0 + } + + //only count callouts where there are no ifdefs + if !inside_if { + if text.re_match(callout_regex, line) { + callout := text.re_find("<(\\d+)>", line) + for key, value in callout { + //trim angle brackets from string + trimmed := callout[key][0]["text"] + trimmed = text.trim_prefix(trimmed, "<") + trimmed = text.trim_suffix(trimmed, ">") + //cast string > int + num := text.atoi(trimmed) + //start counting + if num != prev_num+1 { + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } + prev_num = num + } + } + } + } diff --git a/.github/styles/AsciiDoc/UnsetAttributes.yml b/.github/styles/AsciiDoc/UnsetAttributes.yml new file mode 100644 index 00000000..4945d201 --- /dev/null +++ b/.github/styles/AsciiDoc/UnsetAttributes.yml @@ -0,0 +1,49 @@ +--- +extends: script +level: suggestion +message: "Set attribute directive does not have a corresponding unset attribute directive." +link: https://docs.asciidoctor.org/asciidoc/latest/attributes/unset-attributes/#unset-a-document-attribute-in-the-body +scope: raw +script: | + text := import("text") + matches := [] + + // trim extra whitespace + scope = text.trim_space(scope) + // add a newline, it might be missing + scope += "\n" + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + + attr_regex := "^:[\\w-_]+:.*$" + context_mod_docs_regex := "^:context|_content-type|_mod-docs-content-type:.*$" + attr_name_regex := ":[\\w-_]+:" + attr_name := "" + unset_attr_pref := "" + unset_attr_suff := "" + + for line in text.split(scope, "\n") { + if text.re_match(attr_regex, line) { + if !text.re_match(context_mod_docs_regex, line) { + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + // re_find returns an array holding all matches + attr_name = ((text.re_find(attr_name_regex, line))[0][0])["text"] + unset_attr_pref = `^:!` + text.trim_prefix(attr_name, `:`) + unset_attr_suff = `^` + text.trim_suffix(attr_name, `:`) + `!:` + // loop through lines for every attr found + for line in text.split(scope, "\n") { + if text.re_match(unset_attr_pref, line) { + if len(matches) > 0 { + // remove the most recently added match + matches = matches[:len(matches)-1] + } else if text.re_match(unset_attr_suff, line) { + if len(matches) > 0 { + matches = matches[:len(matches)-1] + } + } + } + } + } + } + } diff --git a/.github/styles/AsciiDoc/ValidAdmonitionBlocks.yml b/.github/styles/AsciiDoc/ValidAdmonitionBlocks.yml new file mode 100644 index 00000000..1ebe0184 --- /dev/null +++ b/.github/styles/AsciiDoc/ValidAdmonitionBlocks.yml @@ -0,0 +1,30 @@ +--- +extends: script +level: error +message: "Unterminated admonition block found in file." +link: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + admon_delim_regex := "^={4}$" + count := 0 + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(admon_delim_regex, line) { + count += 1 + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } else if count > 1 { + count = 0 // admonition block is closed, reset the count + matches = [] + } + } diff --git a/.github/styles/AsciiDoc/ValidCodeBlocks.yml b/.github/styles/AsciiDoc/ValidCodeBlocks.yml new file mode 100644 index 00000000..f7af5c11 --- /dev/null +++ b/.github/styles/AsciiDoc/ValidCodeBlocks.yml @@ -0,0 +1,30 @@ +--- +extends: script +level: error +message: "Unterminated listing block found in file." +link: https://docs.asciidoctor.org/asciidoc/latest/verbatim/listing-blocks/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + listingblock_delim_regex := "^-{4}$" + count := 0 + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(listingblock_delim_regex, line) { + count += 1 + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } else if count > 1 { + count = 0 // listing block is closed, reset the count + matches = [] + } + } diff --git a/.github/styles/AsciiDoc/ValidConditions.yml b/.github/styles/AsciiDoc/ValidConditions.yml new file mode 100644 index 00000000..1bc20cfa --- /dev/null +++ b/.github/styles/AsciiDoc/ValidConditions.yml @@ -0,0 +1,37 @@ +--- +extends: script +level: error +message: "File contains unbalanced if statements. Review the file to ensure it contains matching opening and closing if statements." +link: https://docs.asciidoctor.org/asciidoc/latest/directives/ifdef-ifndef/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + if_regex := "^ifdef::.+\\[\\]" + ifn_regex := "^ifndef::.+\\[\\]" + ifeval_regex := "ifeval::\\[.+\\]" + endif_regex := "^endif::.*\\[\\]" + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(if_regex, line) || text.re_match(ifn_regex, line) || text.re_match(ifeval_regex, line) { + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } else if text.re_match(endif_regex, line) { + if len(matches) > 0 { + //remove the most recently added open ifdef match + matches = matches[:len(matches)-1] + } else if len(matches) == 0 { + //add orphan endif::[] statements + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } + } + } diff --git a/.github/styles/AsciiDoc/ValidTableBlocks.yml b/.github/styles/AsciiDoc/ValidTableBlocks.yml new file mode 100644 index 00000000..ecc74fff --- /dev/null +++ b/.github/styles/AsciiDoc/ValidTableBlocks.yml @@ -0,0 +1,30 @@ +--- +extends: script +level: error +message: "Unterminated table block found in file." +link: https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/ +scope: raw +script: | + text := import("text") + matches := [] + + // clean out multi-line comments + scope = text.re_replace("(?s) *(\n////.*?////\n)", scope, "") + //add a newline, it might be missing + scope += "\n" + + tbl_delim_regex := "^\\|={3,}$" + count := 0 + + for line in text.split(scope, "\n") { + // trim trailing whitespace + line = text.trim_space(line) + if text.re_match(tbl_delim_regex, line) { + count += 1 + start := text.index(scope, line) + matches = append(matches, {begin: start, end: start + len(line)}) + } else if count > 1 { + count = 0 //code block is closed, reset the count + matches = [] + } + } diff --git a/.github/styles/RedHat/Abbreviations.yml b/.github/styles/RedHat/Abbreviations.yml new file mode 100644 index 00000000..102fee41 --- /dev/null +++ b/.github/styles/RedHat/Abbreviations.yml @@ -0,0 +1,9 @@ +--- +extends: existence +level: error +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/abbreviations/ +message: "Do not use periods in all-uppercase abbreviations such as '%s'." +nonword: true +# source: "IBM - Periods with abbreviations, p. 5" +tokens: + - '\b(?:[A-Z]\.){3,5}' diff --git a/.github/styles/RedHat/CaseSensitiveTerms.yml b/.github/styles/RedHat/CaseSensitiveTerms.yml new file mode 100644 index 00000000..f6279863 --- /dev/null +++ b/.github/styles/RedHat/CaseSensitiveTerms.yml @@ -0,0 +1,327 @@ +--- +extends: substitution +ignorecase: false +level: warning +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/casesensitiveterms/ +message: "Use '%s' rather than '%s'." +action: + name: replace +swap: + "(?{7}\s.*$' diff --git a/.github/styles/RedHat/ObviousTerms.yml b/.github/styles/RedHat/ObviousTerms.yml new file mode 100644 index 00000000..fd3f2a32 --- /dev/null +++ b/.github/styles/RedHat/ObviousTerms.yml @@ -0,0 +1,16 @@ +--- +extends: existence +level: suggestion +# link: +message: "Consider not documenting %s because it is self-explanatory." +scope: sentence +# source: +action: + name: remove +tokens: + - 'User field' + - 'Username field' + - 'Password field' + - 'Mail field' + - 'Description field' + - 'Name field' diff --git a/.github/styles/RedHat/OxfordComma.yml b/.github/styles/RedHat/OxfordComma.yml new file mode 100644 index 00000000..2f9d1080 --- /dev/null +++ b/.github/styles/RedHat/OxfordComma.yml @@ -0,0 +1,9 @@ +--- +extends: existence +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/oxfordcomma/ +message: "Use the Oxford comma in '%s'." +scope: sentence +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.github/styles/RedHat/PascalCamelCase.yml b/.github/styles/RedHat/PascalCamelCase.yml new file mode 100644 index 00000000..a2f3ea10 --- /dev/null +++ b/.github/styles/RedHat/PascalCamelCase.yml @@ -0,0 +1,190 @@ +--- +extends: existence +ignorecase: false +level: suggestion +scope: [list, sentence] +link: https://redhat-documentation.github.io/asciidoc-markup-conventions +message: "Consider wrapping this Pascal or Camel case term ('%s') in backticks." +# source: https://github.com/redhat-documentation/vale-at-red-hat/tree/main/.vale/styles/RedHat/PascalCamelCase.yml +tokens: + #PascalCase + - ([A-Z]+[a-z]+){2,} + - ([A-Z]+[a-z]+[A-Z]+){1,} + - ([A-Z]+[A-Z]+[a-z]+){1,} + #camelCase + - ([a-z]+)([A-Z]+[a-z]+){1,} +exceptions: + - '\b[A-Z]{2,}s?' + - 'vCPUs?' + - 3scale + - AGPLv + - AMQ + - API + - AppStream + - AsciiDoc + - AssertJ + - BaseOS + - BitBucket + - BlueStore + - CaaS + - camelCase + - CapEx + - CentOS + - CephFS + - CheckTree + - ClassLoader + - CloudForms + - CodeReady + - ConfigMaps? + - ConnectX + - Convert2RHEL + - CoreOS + - DaemonSet + - DDoS + - DevOps + - DevWorkspace + - DNSSec + - eServer + - eXpress + - eXtenSion + - FaaS + - FCoE + - FileStore + - FireWire + - FreeRADIUS + - GbE + - GBps + - GiB + - GitHub + - GitLab + - GitOps + - GlusterFS + - GNUPro + - GnuTLS + - GraalVM + - GraphQL + - GTID + - HashBase + - HdrHistogram + - Helm + - HyperShift + - IaaS + - IBoE + - IconBurst + - IdM + - IKEv + - InfiniBand + - InnoDB + - IntelliJ + - IntelliSense + - IPoIB + - IPsec + - IPv + - ISeries + - JavaScript + - JBoss + - JetBrains + - JUnit + - kBps + - KiB + - LangTags + - LGPLv + - libOSMesa + - LibreOffice + - libXNVCtrl + - LightPulse + - LinuxONE + - LiquidIO + - ManageIQ + - MariaDB + - MBps + - MegaRAID + - MiB + - MicroProfile + - MongoDB + - MoreUtils + - MySQL + - NetBIOS + - NetcoredebugOutput + - NetWeaver + - NetworkManager + - NetXen + - NetXtreme + - NFSv + - NMState + - NuGet + - NVidia + - NVMe + - OAuth + - objectClass + - OmniSharp + - OneConnect + - OpenEXR + - OpenID + - OpenIPMI + - OpenJDK + - OpenRAN + - OpenRewrite + - OpenSCAP + - OpenShift + - OpenSSH + - OpenSSL + - OpenStack + - OpenTelemetry + - OpenTracing + - OperatorHub + - OpEx + - OSBuild + - OTel + - PaaS + - PackageKit + - PathTools + - PCIe + - PipeWire + - PostgreSQL + - PostScript + - PowerPC + - PowerShell + - ProLiant + - PulseAudio + - PyPA + - PyPI + - QLogic + - ReaR + - RedBoot + - relaxngDatatype + - RESTEasy + - RHEL + - RoCE + - SaaS + - SeaBIOS + - SELinux + - SmallRye + - SmartNIC + - SmartState + - SQLite + - StarOffice + - STMicroelectronics + - SuperLU + - SysV + - TBps + - TiB + - TuneD + - TypeScript + - UltraSPARC + - USBGuard + - vCenter + - vDisk + - vHost + - VMware + - vSphere + - vSwitch + - WebAuthn + - WebSocket + - WireGuard + - XEmacs + - xPaaS + - XString + - XWayland + - YouTube + - ZCentral diff --git a/.github/styles/RedHat/PassiveVoice.yml b/.github/styles/RedHat/PassiveVoice.yml new file mode 100644 index 00000000..67b16afe --- /dev/null +++ b/.github/styles/RedHat/PassiveVoice.yml @@ -0,0 +1,193 @@ +--- +extends: existence +ignorecase: true +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/passivevoice/ +message: "'%s' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice." +# source: "https://redhat-documentation.github.io/supplementary-style-guide/#prerequisites; IBM - Voice, p.35" +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' + - awoken + - beat + - become + - been + - begun + - bent + - beset + - bet + - bid + - bidden + - bitten + - bled + - blown + - born + - bought + - bound + - bred + - broadcast + - broken + - brought + - built + - burnt + - burst + - cast + - caught + - chosen + - clung + - come + - cost + - crept + - cut + - dealt + - dived + - done + - drawn + - dreamt + - driven + - drunk + - dug + - eaten + - fallen + - fed + - felt + - fit + - fled + - flown + - flung + - forbidden + - foregone + - forgiven + - forgotten + - forsaken + - fought + - found + - frozen + - given + - gone + - gotten + - ground + - grown + - heard + - held + - hidden + - hit + - hung + - hurt + - kept + - knelt + - knit + - known + - laid + - lain + - leapt + - learnt + - led + - left + - lent + - let + - lighted + - lost + - made + - meant + - met + - misspelt + - mistaken + - mown + - overcome + - overdone + - overtaken + - overthrown + - paid + - pled + - proven + - put + - quit + - read + - rid + - ridden + - risen + - run + - rung + - said + - sat + - sawn + - seen + - sent + - set + - sewn + - shaken + - shaven + - shed + - shod + - shone + - shorn + - shot + - shown + - shrunk + - shut + - slain + - slept + - slid + - slit + - slung + - smitten + - sold + - sought + - sown + - sped + - spent + - spilt + - spit + - split + - spoken + - spread + - sprung + - spun + - stolen + - stood + - stridden + - striven + - struck + - strung + - stuck + - stung + - stunk + - sung + - sunk + - swept + - swollen + - sworn + - swum + - swung + - taken + - taught + - thought + - thrived + - thrown + - thrust + - told + - torn + - trodden + - understood + - upheld + - upset + - wed + - wept + - withheld + - withstood + - woken + - won + - worn + - wound + - woven + - written + - wrung +exceptions: + - deprecated + - displayed + - imported + - supported + - tested + - trusted diff --git a/.github/styles/RedHat/ProductCentricWriting.yml b/.github/styles/RedHat/ProductCentricWriting.yml new file mode 100644 index 00000000..37216994 --- /dev/null +++ b/.github/styles/RedHat/ProductCentricWriting.yml @@ -0,0 +1,8 @@ +--- +extends: existence +ignorecase: true +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/productcentricwriting/ +message: "Do not use transitive verb constructions like '%s' to grant abilities to inanimate objects. Whenever possible, use direct, user-focused sentences where the subject of the sentence performs the action." +tokens: + - '(allows?|enables?|lets?|permits?)\s(you|customers|the customer|the user|users)' diff --git a/.github/styles/RedHat/README-IBM.adoc b/.github/styles/RedHat/README-IBM.adoc new file mode 100644 index 00000000..7e27b01a --- /dev/null +++ b/.github/styles/RedHat/README-IBM.adoc @@ -0,0 +1,9 @@ += README for Rules from the IBM Style Guide + +All rights for the IBM Style Guide belong to IBM. + +Our sources of inspiration: + +* link:https://github.com/errata-ai/IBM[The primary Vale implementation of the IBM Style Guide] + +* https://www.ibm.com/developerworks/library/styleguidelines/index.html[The DeveloperWorks version of the IBM Style Guide] diff --git a/.github/styles/RedHat/README-proselint.md b/.github/styles/RedHat/README-proselint.md new file mode 100644 index 00000000..b08cef98 --- /dev/null +++ b/.github/styles/RedHat/README-proselint.md @@ -0,0 +1,13 @@ + +Copyright © 2014–2015, Jordan Suchow, Michael Pacer, and Lara A. Ross +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/.github/styles/RedHat/README-write-good.md b/.github/styles/RedHat/README-write-good.md new file mode 100644 index 00000000..ba919b6f --- /dev/null +++ b/.github/styles/RedHat/README-write-good.md @@ -0,0 +1,28 @@ + +Based on [write-good](https://github.com/btford/write-good). + +> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too. + +``` +The MIT License (MIT) + +Copyright (c) 2014 Brian Ford + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` diff --git a/.github/styles/RedHat/ReadabilityGrade.yml b/.github/styles/RedHat/ReadabilityGrade.yml new file mode 100644 index 00000000..a401a67c --- /dev/null +++ b/.github/styles/RedHat/ReadabilityGrade.yml @@ -0,0 +1,9 @@ +--- +extends: readability +grade: 9 +message: "Simplify your language. The calculated Flesch–Kincaid grade level of %s is above the recommended reading grade level of 9." +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/readabilitygrade/ +level: suggestion +metrics: + - Flesch-Kincaid + diff --git a/.github/styles/RedHat/ReleaseNotes.yml b/.github/styles/RedHat/ReleaseNotes.yml new file mode 100644 index 00000000..10ee9c9c --- /dev/null +++ b/.github/styles/RedHat/ReleaseNotes.yml @@ -0,0 +1,11 @@ +--- +extends: substitution +ignorecase: false +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/releasenotes/ +message: "For release notes, consider using '%s' rather than '%s'." +# source: "https://redhat-documentation.github.io/supplementary-style-guide/#release-notes" +# swap maps tokens in form of bad: good +swap: + Now: With this update + Previously: Before this update diff --git a/.github/styles/RedHat/RepeatedWords.yml b/.github/styles/RedHat/RepeatedWords.yml new file mode 100644 index 00000000..3893d9b4 --- /dev/null +++ b/.github/styles/RedHat/RepeatedWords.yml @@ -0,0 +1,16 @@ +--- +extends: repetition +message: "'%s' is repeated." +level: warning +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/repeatedwords/ +ignorecase: false +alpha: true +action: + name: edit + params: + - regex + - '(\w+)(\s\w+)' # pattern + - "$1" # replace +tokens: + - '[^\s\.]+' + - '[^\s]+' diff --git a/.github/styles/RedHat/SelfReferentialText.yml b/.github/styles/RedHat/SelfReferentialText.yml new file mode 100644 index 00000000..36adbf41 --- /dev/null +++ b/.github/styles/RedHat/SelfReferentialText.yml @@ -0,0 +1,14 @@ +--- +extends: existence +ignorecase: true +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/selfreferentialtext/ +message: "Avoid using self-referential text such as '%s'." +# source: "IBM - Audience and medium, p. 22" +tokens: + - this topic + - this module + - this assembly + - this chapter + - this section + - this subsection diff --git a/.github/styles/RedHat/SentenceLength.yml b/.github/styles/RedHat/SentenceLength.yml new file mode 100644 index 00000000..c21f0bc0 --- /dev/null +++ b/.github/styles/RedHat/SentenceLength.yml @@ -0,0 +1,9 @@ +--- +extends: occurrence +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/sentencelength/ +message: "Try to keep sentences to an average of 32 words or fewer." +scope: sentence +# source: "IBM - Conversational style" +max: 32 +token: \b(\w+)\b diff --git a/.github/styles/RedHat/SimpleWords.yml b/.github/styles/RedHat/SimpleWords.yml new file mode 100644 index 00000000..452e7e48 --- /dev/null +++ b/.github/styles/RedHat/SimpleWords.yml @@ -0,0 +1,120 @@ +--- +extends: substitution +ignorecase: true +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/simplewords/ +message: "Use simple language. Consider using '%s' rather than '%s'." +action: + name: replace +swap: + "(?__' + - '<[a-z_]+-[a-z_-]+>' \ No newline at end of file diff --git a/.github/styles/RedHat/Using.yml b/.github/styles/RedHat/Using.yml new file mode 100644 index 00000000..869cdc9b --- /dev/null +++ b/.github/styles/RedHat/Using.yml @@ -0,0 +1,14 @@ +--- +extends: sequence +message: "Use 'by using' instead of 'using' when it follows a noun for clarity and grammatical correctness." +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/using/ +level: warning +action: + name: edit + params: + - regex + - '(\w+)( using)' # pattern + - "$1 by using" # replace +tokens: + - tag: NN|NNP|NNPS|NNS + - pattern: using diff --git a/.github/styles/RedHat/collate-output.tmpl b/.github/styles/RedHat/collate-output.tmpl new file mode 100644 index 00000000..449aa421 --- /dev/null +++ b/.github/styles/RedHat/collate-output.tmpl @@ -0,0 +1,66 @@ +{{- /* See https://github.com/errata-ai/vale/issues/614 */ -}} +{{- /* See https://vale.sh/manual/output/ */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} +{{$table := newTable true}} + +{{- $f = add1 $f -}} +{{- .Path | underline | indent 1 -}} +{{- "\n" -}} + +{{- $msgToLoc := dict -}} +{{- $msgToLvl := dict -}} +{{- $msgToChk := dict -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- $loc := printf "%d:%d" .Line (index .Span 0) -}} + +{{- $locations := get $msgToLoc .Message -}} + +{{- $_ := set $msgToLoc .Message (cat $locations $loc) -}} +{{- $_ := set $msgToLvl .Message $error -}} +{{- $_ := set $msgToChk .Message .Check -}} + +{{end -}} + +{{- range keys $msgToLoc -}} + +{{- $msg := . -}} +{{- $loc := trimPrefix "," ((splitList " " (get $msgToLoc $msg)) | join ",") -}} +{{- $lvl := get $msgToLvl $msg -}} +{{- $chk := get $msgToChk $msg -}} + +{{- $row := list $loc $lvl $msg $chk | toStrings -}} +{{- $table = addRow $table $row -}} + +{{end -}} + +{{- $table = renderTable $table -}} + +{{end}} + +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}} and {{$s}} {{"suggestions" | blue}} in {{$f}} {{$f | int | plural "file" "files"}}. diff --git a/.github/styles/RedHat/meta.json b/.github/styles/RedHat/meta.json new file mode 100644 index 00000000..6099c80b --- /dev/null +++ b/.github/styles/RedHat/meta.json @@ -0,0 +1,4 @@ +{ + "feed": "https://github.com/redhat-documentation/vale-at-red-hat/releases.atom", + "vale_version": ">=2.20.0" +} diff --git a/.github/workflows/lint-with-vale.yml b/.github/workflows/lint-with-vale.yml deleted file mode 100644 index ed0a2b05..00000000 --- a/.github/workflows/lint-with-vale.yml +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: Linting with Vale on pull request -on: [pull_request] - -jobs: - vale: - name: Linting with Vale - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Install Asciidoctor - run: sudo apt-get install -y asciidoctor - - uses: errata-ai/vale-action@reviewdog - with: - files: docs/ - reporter: github-pr-review - fail_on_error: true \ No newline at end of file diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000..21db3aac --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,26 @@ +# This is a basic workflow to help you get started with Actions + +name: Docs-Linting + +# Controls when the action will run. +on: + # Triggers the workflow on push or pull request events but only for the main branch + push: + branches: [ main ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + prose: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@master + + - name: Vale + uses: errata-ai/vale-action@v1.4.2 + with: + debug: true + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} \ No newline at end of file diff --git a/vale.ini b/vale.ini index 8e2c0c45..6757be23 100644 --- a/vale.ini +++ b/vale.ini @@ -1,19 +1,19 @@ StylesPath = .github/styles -MinAlertLevel = error +MinAlertLevel = suggesion IgnoredScopes = code, tt, img, url, a, body.id SkippedScopes = script, style, pre, figure, code, tt, blockquote, listingblock, literalblock -Packages = RedHat +Packages = RedHat, write-good # Match AsciiDoc files. See: https://vale.sh/docs/topics/scoping/ # Ignore files in a directory starting by `.` # to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files [[!.]*.adoc] -BasedOnStyles = RedHat +BasedOnStyles = RedHat, write-good [*.md] @@ -25,4 +25,4 @@ TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\ # Match INI files. See: https://vale.sh/docs/topics/scoping/ [*.ini] -BasedOnStyles = RedHat +BasedOnStyles = RedHat, write-good