From 780513631a1e28c85044ea2a8455464c5712040f Mon Sep 17 00:00:00 2001 From: xanderg2 Date: Wed, 19 Feb 2025 15:56:56 +0000 Subject: [PATCH 1/4] add .vale.ini and styles to .github folder --- .github/styles/.vale-config/1-MDX.ini | 21 ++ .github/styles/Microsoft/AMPM.yml | 9 + .github/styles/Microsoft/Accessibility.yml | 30 ++ .github/styles/Microsoft/Acronyms.yml | 64 +++++ .github/styles/Microsoft/Adverbs.yml | 272 ++++++++++++++++++ .github/styles/Microsoft/Auto.yml | 11 + .github/styles/Microsoft/Avoid.yml | 14 + .github/styles/Microsoft/Contractions.yml | 50 ++++ .github/styles/Microsoft/Dashes.yml | 13 + .github/styles/Microsoft/DateFormat.yml | 8 + .github/styles/Microsoft/DateNumbers.yml | 40 +++ .github/styles/Microsoft/DateOrder.yml | 8 + .github/styles/Microsoft/Ellipses.yml | 9 + .github/styles/Microsoft/FirstPerson.yml | 16 ++ .github/styles/Microsoft/Foreign.yml | 13 + .github/styles/Microsoft/Gender.yml | 8 + .github/styles/Microsoft/GenderBias.yml | 42 +++ .github/styles/Microsoft/GeneralURL.yml | 11 + .github/styles/Microsoft/HeadingAcronyms.yml | 7 + .github/styles/Microsoft/HeadingColons.yml | 8 + .../styles/Microsoft/HeadingPunctuation.yml | 13 + .github/styles/Microsoft/Headings.yml | 28 ++ .github/styles/Microsoft/Hyphens.yml | 14 + .github/styles/Microsoft/Negative.yml | 13 + .github/styles/Microsoft/Ordinal.yml | 13 + .github/styles/Microsoft/OxfordComma.yml | 8 + .github/styles/Microsoft/Passive.yml | 183 ++++++++++++ .github/styles/Microsoft/Percentages.yml | 7 + .github/styles/Microsoft/Plurals.yml | 7 + .github/styles/Microsoft/Quotes.yml | 7 + .github/styles/Microsoft/RangeTime.yml | 13 + .github/styles/Microsoft/Semicolon.yml | 8 + .github/styles/Microsoft/SentenceLength.yml | 7 + .github/styles/Microsoft/Spacing.yml | 8 + .github/styles/Microsoft/Suspended.yml | 7 + .github/styles/Microsoft/Terms.yml | 42 +++ .github/styles/Microsoft/URLFormat.yml | 9 + .github/styles/Microsoft/Units.yml | 16 ++ .github/styles/Microsoft/Vocab.yml | 25 ++ .github/styles/Microsoft/We.yml | 11 + .github/styles/Microsoft/Wordiness.yml | 127 ++++++++ .github/styles/Microsoft/meta.json | 4 + .github/workflows/vale.yml | 10 + .vale.ini | 17 ++ 44 files changed, 1251 insertions(+) create mode 100644 .github/styles/.vale-config/1-MDX.ini create mode 100644 .github/styles/Microsoft/AMPM.yml create mode 100644 .github/styles/Microsoft/Accessibility.yml create mode 100644 .github/styles/Microsoft/Acronyms.yml create mode 100644 .github/styles/Microsoft/Adverbs.yml create mode 100644 .github/styles/Microsoft/Auto.yml create mode 100644 .github/styles/Microsoft/Avoid.yml create mode 100644 .github/styles/Microsoft/Contractions.yml create mode 100644 .github/styles/Microsoft/Dashes.yml create mode 100644 .github/styles/Microsoft/DateFormat.yml create mode 100644 .github/styles/Microsoft/DateNumbers.yml create mode 100644 .github/styles/Microsoft/DateOrder.yml create mode 100644 .github/styles/Microsoft/Ellipses.yml create mode 100644 .github/styles/Microsoft/FirstPerson.yml create mode 100644 .github/styles/Microsoft/Foreign.yml create mode 100644 .github/styles/Microsoft/Gender.yml create mode 100644 .github/styles/Microsoft/GenderBias.yml create mode 100644 .github/styles/Microsoft/GeneralURL.yml create mode 100644 .github/styles/Microsoft/HeadingAcronyms.yml create mode 100644 .github/styles/Microsoft/HeadingColons.yml create mode 100644 .github/styles/Microsoft/HeadingPunctuation.yml create mode 100644 .github/styles/Microsoft/Headings.yml create mode 100644 .github/styles/Microsoft/Hyphens.yml create mode 100644 .github/styles/Microsoft/Negative.yml create mode 100644 .github/styles/Microsoft/Ordinal.yml create mode 100644 .github/styles/Microsoft/OxfordComma.yml create mode 100644 .github/styles/Microsoft/Passive.yml create mode 100644 .github/styles/Microsoft/Percentages.yml create mode 100644 .github/styles/Microsoft/Plurals.yml create mode 100644 .github/styles/Microsoft/Quotes.yml create mode 100644 .github/styles/Microsoft/RangeTime.yml create mode 100644 .github/styles/Microsoft/Semicolon.yml create mode 100644 .github/styles/Microsoft/SentenceLength.yml create mode 100644 .github/styles/Microsoft/Spacing.yml create mode 100644 .github/styles/Microsoft/Suspended.yml create mode 100644 .github/styles/Microsoft/Terms.yml create mode 100644 .github/styles/Microsoft/URLFormat.yml create mode 100644 .github/styles/Microsoft/Units.yml create mode 100644 .github/styles/Microsoft/Vocab.yml create mode 100644 .github/styles/Microsoft/We.yml create mode 100644 .github/styles/Microsoft/Wordiness.yml create mode 100644 .github/styles/Microsoft/meta.json create mode 100644 .github/workflows/vale.yml create mode 100644 .vale.ini diff --git a/.github/styles/.vale-config/1-MDX.ini b/.github/styles/.vale-config/1-MDX.ini new file mode 100644 index 0000000000..d1f1a54de9 --- /dev/null +++ b/.github/styles/.vale-config/1-MDX.ini @@ -0,0 +1,21 @@ +[formats] +mdx = md + +[*.mdx] +CommentDelimiters = {/*, */} + +# Exclude: +# +# `import ...`, `export ...` +# `` +# `...` +# `{ ... }` +TokenIgnores = (?sm)((?:import|export) .+?$), \ +(?)(?!`), \ +(<[A-Z]\w+>.+?<\/[A-Z]\w+>) + +# Exclude: +# +# `` +BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \ +(?sm)^({.+.*}) diff --git a/.github/styles/Microsoft/AMPM.yml b/.github/styles/Microsoft/AMPM.yml new file mode 100644 index 0000000000..8b9fed162a --- /dev/null +++ b/.github/styles/Microsoft/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: Use 'AM' or 'PM' (preceded by a space). +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M' + - '\d{1,2} ?[ap]m' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.github/styles/Microsoft/Accessibility.yml b/.github/styles/Microsoft/Accessibility.yml new file mode 100644 index 0000000000..f5f4829392 --- /dev/null +++ b/.github/styles/Microsoft/Accessibility.yml @@ -0,0 +1,30 @@ +extends: existence +message: "Don't use language (such as '%s') that defines people by their disability." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms +level: suggestion +ignorecase: true +tokens: + - a victim of + - able-bodied + - an epileptic + - birth defect + - crippled + - differently abled + - disabled + - dumb + - handicapped + - handicaps + - healthy person + - hearing-impaired + - lame + - maimed + - mentally handicapped + - missing a limb + - mute + - non-verbal + - normal person + - sight-impaired + - slow learner + - stricken with + - suffers from + - vision-impaired diff --git a/.github/styles/Microsoft/Acronyms.yml b/.github/styles/Microsoft/Acronyms.yml new file mode 100644 index 0000000000..308ff7c0ed --- /dev/null +++ b/.github/styles/Microsoft/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "'%s' has no definition." +link: https://docs.microsoft.com/en-us/style-guide/acronyms +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.github/styles/Microsoft/Adverbs.yml b/.github/styles/Microsoft/Adverbs.yml new file mode 100644 index 0000000000..5619f99d8c --- /dev/null +++ b/.github/styles/Microsoft/Adverbs.yml @@ -0,0 +1,272 @@ +extends: existence +message: "Remove '%s' if it's not important to the meaning of the statement." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences +ignorecase: true +level: warning +action: + name: remove +tokens: + - abnormally + - absentmindedly + - accidentally + - adventurously + - anxiously + - arrogantly + - awkwardly + - bashfully + - beautifully + - bitterly + - bleakly + - blindly + - blissfully + - boastfully + - boldly + - bravely + - briefly + - brightly + - briskly + - broadly + - busily + - calmly + - carefully + - carelessly + - cautiously + - cheerfully + - cleverly + - closely + - coaxingly + - colorfully + - continually + - coolly + - courageously + - crossly + - cruelly + - curiously + - daintily + - dearly + - deceivingly + - deeply + - defiantly + - deliberately + - delightfully + - diligently + - dimly + - doubtfully + - dreamily + - easily + - effectively + - elegantly + - energetically + - enormously + - enthusiastically + - excitedly + - extremely + - fairly + - faithfully + - famously + - ferociously + - fervently + - fiercely + - fondly + - foolishly + - fortunately + - frankly + - frantically + - freely + - frenetically + - frightfully + - furiously + - generally + - generously + - gently + - gladly + - gleefully + - gracefully + - gratefully + - greatly + - greedily + - happily + - hastily + - healthily + - heavily + - helplessly + - honestly + - hopelessly + - hungrily + - innocently + - inquisitively + - intensely + - intently + - interestingly + - inwardly + - irritably + - jaggedly + - jealously + - jovially + - joyfully + - joyously + - jubilantly + - judgmentally + - justly + - keenly + - kiddingly + - kindheartedly + - knavishly + - knowingly + - knowledgeably + - lazily + - lightly + - limply + - lively + - loftily + - longingly + - loosely + - loudly + - lovingly + - loyally + - madly + - majestically + - meaningfully + - mechanically + - merrily + - miserably + - mockingly + - mortally + - mysteriously + - naturally + - nearly + - neatly + - nervously + - nicely + - noisily + - obediently + - obnoxiously + - oddly + - offensively + - optimistically + - overconfidently + - painfully + - partially + - patiently + - perfectly + - playfully + - politely + - poorly + - positively + - potentially + - powerfully + - promptly + - properly + - punctually + - quaintly + - queasily + - queerly + - questionably + - quickly + - quietly + - quirkily + - quite + - quizzically + - randomly + - rapidly + - rarely + - readily + - really + - reassuringly + - recklessly + - regularly + - reluctantly + - repeatedly + - reproachfully + - restfully + - righteously + - rightfully + - rigidly + - roughly + - rudely + - safely + - scarcely + - scarily + - searchingly + - sedately + - seemingly + - selfishly + - separately + - seriously + - shakily + - sharply + - sheepishly + - shrilly + - shyly + - silently + - sleepily + - slowly + - smoothly + - softly + - solemnly + - solidly + - speedily + - stealthily + - sternly + - strictly + - suddenly + - supposedly + - surprisingly + - suspiciously + - sweetly + - swiftly + - sympathetically + - tenderly + - tensely + - terribly + - thankfully + - thoroughly + - thoughtfully + - tightly + - tremendously + - triumphantly + - truthfully + - ultimately + - unabashedly + - unaccountably + - unbearably + - unethically + - unexpectedly + - unfortunately + - unimpressively + - unnaturally + - unnecessarily + - urgently + - usefully + - uselessly + - utterly + - vacantly + - vaguely + - vainly + - valiantly + - vastly + - verbally + - very + - viciously + - victoriously + - violently + - vivaciously + - voluntarily + - warmly + - weakly + - wearily + - wetly + - wholly + - wildly + - willfully + - wisely + - woefully + - wonderfully + - worriedly + - yawningly + - yearningly + - yieldingly + - youthfully + - zealously + - zestfully + - zestily diff --git a/.github/styles/Microsoft/Auto.yml b/.github/styles/Microsoft/Auto.yml new file mode 100644 index 0000000000..4da4393530 --- /dev/null +++ b/.github/styles/Microsoft/Auto.yml @@ -0,0 +1,11 @@ +extends: existence +message: "In general, don't hyphenate '%s'." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/auto +ignorecase: true +level: error +action: + name: convert + params: + - simple +tokens: + - 'auto-\w+' diff --git a/.github/styles/Microsoft/Avoid.yml b/.github/styles/Microsoft/Avoid.yml new file mode 100644 index 0000000000..dab7822c79 --- /dev/null +++ b/.github/styles/Microsoft/Avoid.yml @@ -0,0 +1,14 @@ +extends: existence +message: "Don't use '%s'. See the A-Z word list for details." +# See the A-Z word list +link: https://docs.microsoft.com/en-us/style-guide +ignorecase: true +level: error +tokens: + - abortion + - and so on + - app(?:lication)?s? (?:developer|program) + - app(?:lication)? file + - backbone + - backend + - contiguous selection diff --git a/.github/styles/Microsoft/Contractions.yml b/.github/styles/Microsoft/Contractions.yml new file mode 100644 index 0000000000..8c81dcbce7 --- /dev/null +++ b/.github/styles/Microsoft/Contractions.yml @@ -0,0 +1,50 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions +level: error +ignorecase: true +action: + name: replace +swap: + are not: aren't + cannot: can't + could not: couldn't + did not: didn't + do not: don't + does not: doesn't + has not: hasn't + have not: haven't + how is: how's + is not: isn't + + 'it is(?!\.)': it's + 'it''s(?=\.)': it is + + should not: shouldn't + + "that is(?![.,])": that's + 'that''s(?=\.)': that is + + 'they are(?!\.)': they're + 'they''re(?=\.)': they are + + was not: wasn't + + 'we are(?!\.)': we're + 'we''re(?=\.)': we are + + 'we have(?!\.)': we've + 'we''ve(?=\.)': we have + + were not: weren't + + 'what is(?!\.)': what's + 'what''s(?=\.)': what is + + 'when is(?!\.)': when's + 'when''s(?=\.)': when is + + 'where is(?!\.)': where's + 'where''s(?=\.)': where is + + will not: won't diff --git a/.github/styles/Microsoft/Dashes.yml b/.github/styles/Microsoft/Dashes.yml new file mode 100644 index 0000000000..72b05ba3e5 --- /dev/null +++ b/.github/styles/Microsoft/Dashes.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Remove the spaces around '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes +ignorecase: true +nonword: true +level: error +action: + name: edit + params: + - trim + - " " +tokens: + - '\s[—–]\s|\s[—–]|[—–]\s' diff --git a/.github/styles/Microsoft/DateFormat.yml b/.github/styles/Microsoft/DateFormat.yml new file mode 100644 index 0000000000..196531394a --- /dev/null +++ b/.github/styles/Microsoft/DateFormat.yml @@ -0,0 +1,8 @@ +extends: existence +message: Use 'July 31, 2016' format, not '%s'. +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}' diff --git a/.github/styles/Microsoft/DateNumbers.yml b/.github/styles/Microsoft/DateNumbers.yml new file mode 100644 index 0000000000..14d46747ca --- /dev/null +++ b/.github/styles/Microsoft/DateNumbers.yml @@ -0,0 +1,40 @@ +extends: existence +message: "Don't use ordinal numbers for dates." +link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates +level: error +nonword: true +ignorecase: true +raw: + - \b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?)\b\s* +tokens: + - first + - second + - third + - fourth + - fifth + - sixth + - seventh + - eighth + - ninth + - tenth + - eleventh + - twelfth + - thirteenth + - fourteenth + - fifteenth + - sixteenth + - seventeenth + - eighteenth + - nineteenth + - twentieth + - twenty-first + - twenty-second + - twenty-third + - twenty-fourth + - twenty-fifth + - twenty-sixth + - twenty-seventh + - twenty-eighth + - twenty-ninth + - thirtieth + - thirty-first diff --git a/.github/styles/Microsoft/DateOrder.yml b/.github/styles/Microsoft/DateOrder.yml new file mode 100644 index 0000000000..12d69ba51e --- /dev/null +++ b/.github/styles/Microsoft/DateOrder.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Always spell out the name of the month." +link: https://docs.microsoft.com/en-us/style-guide/numbers#numbers-in-dates +ignorecase: true +level: error +nonword: true +tokens: + - '\b\d{1,2}/\d{1,2}/(?:\d{4}|\d{2})\b' diff --git a/.github/styles/Microsoft/Ellipses.yml b/.github/styles/Microsoft/Ellipses.yml new file mode 100644 index 0000000000..320457a8bc --- /dev/null +++ b/.github/styles/Microsoft/Ellipses.yml @@ -0,0 +1,9 @@ +extends: existence +message: "In general, don't use an ellipsis." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/ellipses +nonword: true +level: warning +action: + name: remove +tokens: + - '\.\.\.' diff --git a/.github/styles/Microsoft/FirstPerson.yml b/.github/styles/Microsoft/FirstPerson.yml new file mode 100644 index 0000000000..f58dea3142 --- /dev/null +++ b/.github/styles/Microsoft/FirstPerson.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Use first person (such as '%s') sparingly." +link: https://docs.microsoft.com/en-us/style-guide/grammar/person +ignorecase: true +level: warning +nonword: true +tokens: + - (?:^|\s)I(?=\s) + - (?:^|\s)I(?=,\s) + - \bI'd\b + - \bI'll\b + - \bI'm\b + - \bI've\b + - \bme\b + - \bmy\b + - \bmine\b diff --git a/.github/styles/Microsoft/Foreign.yml b/.github/styles/Microsoft/Foreign.yml new file mode 100644 index 0000000000..0d3d6002a9 --- /dev/null +++ b/.github/styles/Microsoft/Foreign.yml @@ -0,0 +1,13 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words +ignorecase: true +level: error +nonword: true +action: + name: replace +swap: + '\b(?:eg|e\.g\.)[\s,]': for example + '\b(?:ie|i\.e\.)[\s,]': that is + '\b(?:viz\.)[\s,]': namely + '\b(?:ergo)[\s,]': therefore diff --git a/.github/styles/Microsoft/Gender.yml b/.github/styles/Microsoft/Gender.yml new file mode 100644 index 0000000000..47c0802479 --- /dev/null +++ b/.github/styles/Microsoft/Gender.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't use '%s'." +link: https://github.com/MicrosoftDocs/microsoft-style-guide/blob/master/styleguide/grammar/nouns-pronouns.md#pronouns-and-gender +level: error +ignorecase: true +tokens: + - he/she + - s/he diff --git a/.github/styles/Microsoft/GenderBias.yml b/.github/styles/Microsoft/GenderBias.yml new file mode 100644 index 0000000000..fc987b94e9 --- /dev/null +++ b/.github/styles/Microsoft/GenderBias.yml @@ -0,0 +1,42 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: error +action: + name: replace +swap: + (?:alumna|alumnus): graduate + (?:alumnae|alumni): graduates + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + manpower: personnel + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + steward(?:ess)?: flight attendant + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/.github/styles/Microsoft/GeneralURL.yml b/.github/styles/Microsoft/GeneralURL.yml new file mode 100644 index 0000000000..dcef503d99 --- /dev/null +++ b/.github/styles/Microsoft/GeneralURL.yml @@ -0,0 +1,11 @@ +extends: existence +message: "For a general audience, use 'address' rather than 'URL'." +link: https://docs.microsoft.com/en-us/style-guide/urls-web-addresses +level: warning +action: + name: replace + params: + - URL + - address +tokens: + - URL diff --git a/.github/styles/Microsoft/HeadingAcronyms.yml b/.github/styles/Microsoft/HeadingAcronyms.yml new file mode 100644 index 0000000000..9dc3b6c2de --- /dev/null +++ b/.github/styles/Microsoft/HeadingAcronyms.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Avoid using acronyms in a title or heading." +link: https://docs.microsoft.com/en-us/style-guide/acronyms#be-careful-with-acronyms-in-titles-and-headings +level: warning +scope: heading +tokens: + - '[A-Z]{2,4}' diff --git a/.github/styles/Microsoft/HeadingColons.yml b/.github/styles/Microsoft/HeadingColons.yml new file mode 100644 index 0000000000..7013c39148 --- /dev/null +++ b/.github/styles/Microsoft/HeadingColons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Capitalize '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/colons +nonword: true +level: error +scope: heading +tokens: + - ':\s[a-z]' diff --git a/.github/styles/Microsoft/HeadingPunctuation.yml b/.github/styles/Microsoft/HeadingPunctuation.yml new file mode 100644 index 0000000000..4954cb11ae --- /dev/null +++ b/.github/styles/Microsoft/HeadingPunctuation.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't use end punctuation in headings." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +nonword: true +level: warning +scope: heading +action: + name: edit + params: + - trim_right + - ".?!" +tokens: + - "[a-z][.?!]$" diff --git a/.github/styles/Microsoft/Headings.yml b/.github/styles/Microsoft/Headings.yml new file mode 100644 index 0000000000..63624edc1b --- /dev/null +++ b/.github/styles/Microsoft/Headings.yml @@ -0,0 +1,28 @@ +extends: capitalization +message: "'%s' should use sentence-style capitalization." +link: https://docs.microsoft.com/en-us/style-guide/capitalization +level: suggestion +scope: heading +match: $sentence +indicators: + - ':' +exceptions: + - Azure + - CLI + - Code + - Cosmos + - Docker + - Emmet + - I + - Kubernetes + - Linux + - macOS + - Marketplace + - MongoDB + - REPL + - Studio + - TypeScript + - URLs + - Visual + - VS + - Windows diff --git a/.github/styles/Microsoft/Hyphens.yml b/.github/styles/Microsoft/Hyphens.yml new file mode 100644 index 0000000000..7e5731c995 --- /dev/null +++ b/.github/styles/Microsoft/Hyphens.yml @@ -0,0 +1,14 @@ +extends: existence +message: "'%s' doesn't need a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens +level: warning +ignorecase: false +nonword: true +action: + name: edit + params: + - regex + - "-" + - " " +tokens: + - '\b[^\s-]+ly-\w+\b' diff --git a/.github/styles/Microsoft/Negative.yml b/.github/styles/Microsoft/Negative.yml new file mode 100644 index 0000000000..d73221f539 --- /dev/null +++ b/.github/styles/Microsoft/Negative.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Form a negative number with an en dash, not a hyphen." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +action: + name: edit + params: + - regex + - "-" + - "–" +tokens: + - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/.github/styles/Microsoft/Ordinal.yml b/.github/styles/Microsoft/Ordinal.yml new file mode 100644 index 0000000000..e3483e380c --- /dev/null +++ b/.github/styles/Microsoft/Ordinal.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Don't add -ly to an ordinal number." +link: https://docs.microsoft.com/en-us/style-guide/numbers +level: error +action: + name: edit + params: + - trim + - ly +tokens: + - firstly + - secondly + - thirdly diff --git a/.github/styles/Microsoft/OxfordComma.yml b/.github/styles/Microsoft/OxfordComma.yml new file mode 100644 index 0000000000..493b55c3ce --- /dev/null +++ b/.github/styles/Microsoft/OxfordComma.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas +scope: sentence +level: suggestion +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.github/styles/Microsoft/Passive.yml b/.github/styles/Microsoft/Passive.yml new file mode 100644 index 0000000000..102d377cac --- /dev/null +++ b/.github/styles/Microsoft/Passive.yml @@ -0,0 +1,183 @@ +extends: existence +message: "'%s' looks like passive voice." +ignorecase: true +level: suggestion +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 diff --git a/.github/styles/Microsoft/Percentages.yml b/.github/styles/Microsoft/Percentages.yml new file mode 100644 index 0000000000..b68a7363f4 --- /dev/null +++ b/.github/styles/Microsoft/Percentages.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use a numeral plus the units." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +tokens: + - '\b[a-zA-z]+\spercent\b' diff --git a/.github/styles/Microsoft/Plurals.yml b/.github/styles/Microsoft/Plurals.yml new file mode 100644 index 0000000000..1bb6660ade --- /dev/null +++ b/.github/styles/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/.github/styles/Microsoft/Quotes.yml b/.github/styles/Microsoft/Quotes.yml new file mode 100644 index 0000000000..38f4976061 --- /dev/null +++ b/.github/styles/Microsoft/Quotes.yml @@ -0,0 +1,7 @@ +extends: existence +message: 'Punctuation should be inside the quotes.' +link: https://docs.microsoft.com/en-us/style-guide/punctuation/quotation-marks +level: error +nonword: true +tokens: + - '["“][^"”“]+["”][.,]' diff --git a/.github/styles/Microsoft/RangeTime.yml b/.github/styles/Microsoft/RangeTime.yml new file mode 100644 index 0000000000..72d8bbfbe3 --- /dev/null +++ b/.github/styles/Microsoft/RangeTime.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Use 'to' instead of a dash in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/numbers +nonword: true +level: error +action: + name: edit + params: + - regex + - "[-–]" + - "to" +tokens: + - '\b(?:AM|PM)\s?[-–]\s?.+(?:AM|PM)\b' diff --git a/.github/styles/Microsoft/Semicolon.yml b/.github/styles/Microsoft/Semicolon.yml new file mode 100644 index 0000000000..4d905467dd --- /dev/null +++ b/.github/styles/Microsoft/Semicolon.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Try to simplify this sentence." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/semicolons +nonword: true +scope: sentence +level: suggestion +tokens: + - ';' diff --git a/.github/styles/Microsoft/SentenceLength.yml b/.github/styles/Microsoft/SentenceLength.yml new file mode 100644 index 0000000000..f248cf0513 --- /dev/null +++ b/.github/styles/Microsoft/SentenceLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: "Try to keep sentences short (< 30 words)." +scope: sentence +level: suggestion +max: 30 +token: \b(\w+)\b + diff --git a/.github/styles/Microsoft/Spacing.yml b/.github/styles/Microsoft/Spacing.yml new file mode 100644 index 0000000000..bbd10e51df --- /dev/null +++ b/.github/styles/Microsoft/Spacing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should have one space." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods +level: error +nonword: true +tokens: + - '[a-z][.?!] {2,}[A-Z]' + - '[a-z][.?!][A-Z]' diff --git a/.github/styles/Microsoft/Suspended.yml b/.github/styles/Microsoft/Suspended.yml new file mode 100644 index 0000000000..7282e9c9cf --- /dev/null +++ b/.github/styles/Microsoft/Suspended.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't use '%s' unless space is limited." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/hyphens +ignorecase: true +level: warning +tokens: + - '\w+- and \w+-' diff --git a/.github/styles/Microsoft/Terms.yml b/.github/styles/Microsoft/Terms.yml new file mode 100644 index 0000000000..65fca10aaa --- /dev/null +++ b/.github/styles/Microsoft/Terms.yml @@ -0,0 +1,42 @@ +extends: substitution +message: "Prefer '%s' over '%s'." +# term preference should be based on microsoft style guide, such as +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter +level: warning +ignorecase: true +action: + name: replace +swap: + "(?:agent|virtual assistant|intelligent personal assistant)": personal digital assistant + "(?:assembler|machine language)": assembly language + "(?:drive C:|drive C>|C: drive)": drive C + "(?:internet bot|web robot)s?": bot(s) + "(?:microsoft cloud|the cloud)": cloud + "(?:mobile|smart) ?phone": phone + "24/7": every day + "audio(?:-| )book": audiobook + "back(?:-| )light": backlight + "chat ?bots?": chatbot(s) + adaptor: adapter + administrate: administer + afterwards: afterward + alphabetic: alphabetical + alphanumerical: alphanumeric + an URL: a URL + anti-aliasing: antialiasing + anti-malware: antimalware + anti-spyware: antispyware + anti-virus: antivirus + appendixes: appendices + artificial intelligence: AI + caap: CaaP + conversation-as-a-platform: conversation as a platform + eb: EB + gb: GB + gbps: Gbps + kb: KB + keypress: keystroke + mb: MB + pb: PB + tb: TB + zb: ZB diff --git a/.github/styles/Microsoft/URLFormat.yml b/.github/styles/Microsoft/URLFormat.yml new file mode 100644 index 0000000000..4e24aa59fe --- /dev/null +++ b/.github/styles/Microsoft/URLFormat.yml @@ -0,0 +1,9 @@ +extends: substitution +message: Use 'of' (not 'for') to describe the relationship of the word URL to a resource. +ignorecase: true +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/url +level: suggestion +action: + name: replace +swap: + URL for: URL of diff --git a/.github/styles/Microsoft/Units.yml b/.github/styles/Microsoft/Units.yml new file mode 100644 index 0000000000..f062418ee0 --- /dev/null +++ b/.github/styles/Microsoft/Units.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Don't spell out the number in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/units-of-measure-terms +level: error +raw: + - '[a-zA-Z]+\s' +tokens: + - '(?:centi|milli)?meters' + - '(?:kilo)?grams' + - '(?:kilo)?meters' + - '(?:mega)?pixels' + - cm + - inches + - lb + - miles + - pounds diff --git a/.github/styles/Microsoft/Vocab.yml b/.github/styles/Microsoft/Vocab.yml new file mode 100644 index 0000000000..eebe97b15e --- /dev/null +++ b/.github/styles/Microsoft/Vocab.yml @@ -0,0 +1,25 @@ +extends: existence +message: "Verify your use of '%s' with the A-Z word list." +link: 'https://docs.microsoft.com/en-us/style-guide' +level: suggestion +ignorecase: true +tokens: + - above + - accessible + - actionable + - against + - alarm + - alert + - alias + - allows? + - and/or + - as well as + - assure + - author + - avg + - beta + - ensure + - he + - insure + - sample + - she diff --git a/.github/styles/Microsoft/We.yml b/.github/styles/Microsoft/We.yml new file mode 100644 index 0000000000..97c901c1ba --- /dev/null +++ b/.github/styles/Microsoft/We.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Try to avoid using first-person plural like '%s'." +link: https://docs.microsoft.com/en-us/style-guide/grammar/person#avoid-first-person-plural +level: warning +ignorecase: true +tokens: + - we + - we'(?:ve|re) + - ours? + - us + - let's diff --git a/.github/styles/Microsoft/Wordiness.yml b/.github/styles/Microsoft/Wordiness.yml new file mode 100644 index 0000000000..3d008d1894 --- /dev/null +++ b/.github/styles/Microsoft/Wordiness.yml @@ -0,0 +1,127 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences +ignorecase: true +level: suggestion +action: + name: replace +swap: + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell + (?:previous|prior) to: before + (?:utilize|make use of): use + a (?:large)? majority of: most + a (?:large)? number of: many + a myriad of: myriad + adversely impact: hurt + all across: across + all of (?!a sudden|these): all + all of a sudden: suddenly + all of these: these + all-time record: record + almost all: most + almost never: seldom + along the lines of: similar to + an adequate number of: enough + an appreciable number of: many + an estimated: about + any and all: all + are in agreement: agree + as a matter of fact: in fact + as a means of: to + as a result of: because of + as of yet: yet + as per: per + at a later date: later + at all times: always + at the present time: now + at this point in time: at this point + based in large part on: based on + based on the fact that: because + basic necessity: necessity + because of the fact that: because + came to a realization: realized + came to an abrupt end: ended abruptly + carry out an evaluation of: evaluate + close down: close + closed down: closed + complete stranger: stranger + completely separate: separate + concerning the matter of: regarding + conduct a review of: review + conduct an investigation: investigate + conduct experiments: experiment + continue on: continue + despite the fact that: although + disappear from sight: disappear + doomed to fail: doomed + drag and drop: drag + drag-and-drop: drag + due to the fact that: because + during the period of: during + during the time that: while + emergency situation: emergency + establish connectivity: connect + except when: unless + excessive number: too many + extend an invitation: invite + fall down: fall + fell down: fell + for the duration of: during + gather together: gather + has the ability to: can + has the capacity to: can + has the opportunity to: could + hold a meeting: meet + if this is not the case: if not + in a careful manner: carefully + in a thoughtful manner: thoughtfully + in a timely manner: timely + in addition: also + in an effort to: to + in between: between + in lieu of: instead of + in many cases: often + in most cases: usually + in order to: to + in some cases: sometimes + in spite of the fact that: although + in spite of: despite + in the (?:very)? near future: soon + in the event that: if + in the neighborhood of: roughly + in the vicinity of: close to + it would appear that: apparently + lift up: lift + made reference to: referred to + make reference to: refer to + mix together: mix + none at all: none + not in a position to: unable + not possible: impossible + of major importance: important + perform an assessment of: assess + pertaining to: about + place an order: order + plays a key role in: is essential to + present time: now + readily apparent: apparent + some of the: some + span across: span + subsequent to: after + successfully complete: complete + sufficient number (?:of)?: enough + take action: act + take into account: consider + the question as to whether: whether + there is no doubt but that: doubtless + this day and age: this age + this is a subject that: this subject + time (?:frame|period): time + under the provisions of: under + until such time as: until + used for fuel purposes: used for fuel + whether or not: whether + with regard to: regarding + with the exception of: except for diff --git a/.github/styles/Microsoft/meta.json b/.github/styles/Microsoft/meta.json new file mode 100644 index 0000000000..297719bbbf --- /dev/null +++ b/.github/styles/Microsoft/meta.json @@ -0,0 +1,4 @@ +{ + "feed": "https://github.com/errata-ai/Microsoft/releases.atom", + "vale_version": ">=1.0.0" +} diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 0000000000..499cf67983 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,10 @@ +name: reviewdog +on: [pull_request] + +jobs: + vale: + name: runner / vale + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: errata-ai/vale-action@v2.1.1 diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..02b49b2acd --- /dev/null +++ b/.vale.ini @@ -0,0 +1,17 @@ +StylesPath = .github/styles + +MinAlertLevel = suggestion + +Packages = Microsoft, MDX + +[*.{md}] +# ^ This section applies to only Markdown files. +# +# You can change (or add) file extensions here +# to apply these settings to other file types. +# +# For example, to apply these settings to both +# Markdown and reStructuredText: +# +# [*.{md,rst}] +BasedOnStyles = Vale, Microsoft From 658a2e46a5dfe0351a50d473cee4cf79b44e75d0 Mon Sep 17 00:00:00 2001 From: xanderg2 Date: Wed, 19 Feb 2025 16:06:22 +0000 Subject: [PATCH 2/4] add dirs --- .github/workflows/vale.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index 499cf67983..609c248eff 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -8,3 +8,7 @@ jobs: steps: - uses: actions/checkout@v4 - uses: errata-ai/vale-action@v2.1.1 + with: + files: + '["/postgraphile/website", "/grafast/website", + "/graphile-build/website", "/utils/wesbite"]' From 8b74d075d2a0f3f89f05aea0c68f004f584d1049 Mon Sep 17 00:00:00 2001 From: xanderg2 Date: Wed, 19 Feb 2025 16:51:19 +0000 Subject: [PATCH 3/4] fix directory root --- .github/workflows/vale.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index 609c248eff..5036f81dd3 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -10,5 +10,5 @@ jobs: - uses: errata-ai/vale-action@v2.1.1 with: files: - '["/postgraphile/website", "/grafast/website", - "/graphile-build/website", "/utils/wesbite"]' + '["postgraphile/website", "grafast/website", + "graphile-build/website", "utils/wesbite"]' From 2c830b0be97c527053f5ba99aaf955f282372463 Mon Sep 17 00:00:00 2001 From: xanderg2 Date: Sat, 22 Feb 2025 14:43:51 +0000 Subject: [PATCH 4/4] add a bunch of rules and fix some things --- .../Acronyms.yml => Graphile/Acronyms} | 2 ++ .../{Microsoft => Graphile}/Headings.yml | 6 +++++- .github/styles/Microsoft/Accessibility.yml | 4 +++- .../styles/Microsoft/Acronyms.yml.disabled | 1 + .../{Adverbs.yml => Adverbs.yml.disabled} | 1 + ...ractions.yml => Contractions.yml.disabled} | 1 + .../{Dashes.yml => Dashes.yml.disabled} | 1 + ...DateFormat.yml => DateFormat.yml.disabled} | 5 ++++- .../{Ellipses.yml => Ellipses.yml.disabled} | 1 + ...rstPerson.yml => FirstPerson.yml.disabled} | 1 + .../{Foreign.yml => Foreign.yml.disabled} | 1 + ...GeneralURL.yml => GeneralURL.yml.disabled} | 1 + ...onyms.yml => HeadingAcronyms.yml.disabled} | 3 ++- .../styles/Microsoft/Headings.yml.disabled | 1 + .github/styles/Microsoft/Hyphens.yml | 2 ++ .../{Passive.yml => Passive.yml.disabled} | 1 + .github/styles/Microsoft/Quotes.yml | 2 +- .../{Semicolon.yml => Semicolon.yml.disabled} | 3 ++- ...Length.yml => SentenceLength.yml.disabled} | 2 +- .github/styles/Microsoft/Spacing.yml | 4 ++-- .../{Vocab.yml => Vocab.yml.disabled} | 3 ++- .../Microsoft/{We.yml => We.yml.disabled} | 1 + .../config/vocabularies/Graphile/accept.txt | 21 +++++++++++++++++++ .../config/vocabularies/Graphile/reject.txt | 0 .vale.ini | 4 +++- utils/website/graphile-config/preset.md | 6 +++--- utils/website/graphile-export/exportable.md | 4 ++-- utils/website/pg-sql2/index.md | 2 +- .../tamedevil/api/te-safe-key-or-throw.md | 4 ++-- utils/website/tamedevil/index.md | 4 ++-- 30 files changed, 71 insertions(+), 21 deletions(-) rename .github/styles/{Microsoft/Acronyms.yml => Graphile/Acronyms} (98%) rename .github/styles/{Microsoft => Graphile}/Headings.yml (86%) create mode 100644 .github/styles/Microsoft/Acronyms.yml.disabled rename .github/styles/Microsoft/{Adverbs.yml => Adverbs.yml.disabled} (99%) rename .github/styles/Microsoft/{Contractions.yml => Contractions.yml.disabled} (98%) rename .github/styles/Microsoft/{Dashes.yml => Dashes.yml.disabled} (96%) rename .github/styles/Microsoft/{DateFormat.yml => DateFormat.yml.disabled} (56%) rename .github/styles/Microsoft/{Ellipses.yml => Ellipses.yml.disabled} (95%) rename .github/styles/Microsoft/{FirstPerson.yml => FirstPerson.yml.disabled} (96%) rename .github/styles/Microsoft/{Foreign.yml => Foreign.yml.disabled} (97%) rename .github/styles/Microsoft/{GeneralURL.yml => GeneralURL.yml.disabled} (96%) rename .github/styles/Microsoft/{HeadingAcronyms.yml => HeadingAcronyms.yml.disabled} (89%) create mode 100644 .github/styles/Microsoft/Headings.yml.disabled rename .github/styles/Microsoft/{Passive.yml => Passive.yml.disabled} (99%) rename .github/styles/Microsoft/{Semicolon.yml => Semicolon.yml.disabled} (91%) rename .github/styles/Microsoft/{SentenceLength.yml => SentenceLength.yml.disabled} (92%) rename .github/styles/Microsoft/{Vocab.yml => Vocab.yml.disabled} (83%) rename .github/styles/Microsoft/{We.yml => We.yml.disabled} (96%) create mode 100644 .github/styles/config/vocabularies/Graphile/accept.txt create mode 100644 .github/styles/config/vocabularies/Graphile/reject.txt diff --git a/.github/styles/Microsoft/Acronyms.yml b/.github/styles/Graphile/Acronyms similarity index 98% rename from .github/styles/Microsoft/Acronyms.yml rename to .github/styles/Graphile/Acronyms index 308ff7c0ed..a1b1763f88 100644 --- a/.github/styles/Microsoft/Acronyms.yml +++ b/.github/styles/Graphile/Acronyms @@ -62,3 +62,5 @@ exceptions: - XSS - YAML - ZIP + - ESM + - AWS diff --git a/.github/styles/Microsoft/Headings.yml b/.github/styles/Graphile/Headings.yml similarity index 86% rename from .github/styles/Microsoft/Headings.yml rename to .github/styles/Graphile/Headings.yml index 63624edc1b..4c9e5b9659 100644 --- a/.github/styles/Microsoft/Headings.yml +++ b/.github/styles/Graphile/Headings.yml @@ -5,7 +5,7 @@ level: suggestion scope: heading match: $sentence indicators: - - ':' + - ":" exceptions: - Azure - CLI @@ -26,3 +26,7 @@ exceptions: - Visual - VS - Windows + - PostGraphile + - Grafast + - Graphile + - EXPORTABLE diff --git a/.github/styles/Microsoft/Accessibility.yml b/.github/styles/Microsoft/Accessibility.yml index f5f4829392..6e3b97a17a 100644 --- a/.github/styles/Microsoft/Accessibility.yml +++ b/.github/styles/Microsoft/Accessibility.yml @@ -1,5 +1,7 @@ +# doesnt seem relevant to these docs extends: existence -message: "Don't use language (such as '%s') that defines people by their disability." +message: + "Don't use language (such as '%s') that defines people by their disability." link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms level: suggestion ignorecase: true diff --git a/.github/styles/Microsoft/Acronyms.yml.disabled b/.github/styles/Microsoft/Acronyms.yml.disabled new file mode 100644 index 0000000000..8ca9f4fa11 --- /dev/null +++ b/.github/styles/Microsoft/Acronyms.yml.disabled @@ -0,0 +1 @@ +# copied to graphile/acronyms diff --git a/.github/styles/Microsoft/Adverbs.yml b/.github/styles/Microsoft/Adverbs.yml.disabled similarity index 99% rename from .github/styles/Microsoft/Adverbs.yml rename to .github/styles/Microsoft/Adverbs.yml.disabled index 5619f99d8c..0945a6b956 100644 --- a/.github/styles/Microsoft/Adverbs.yml +++ b/.github/styles/Microsoft/Adverbs.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "Remove '%s' if it's not important to the meaning of the statement." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences diff --git a/.github/styles/Microsoft/Contractions.yml b/.github/styles/Microsoft/Contractions.yml.disabled similarity index 98% rename from .github/styles/Microsoft/Contractions.yml rename to .github/styles/Microsoft/Contractions.yml.disabled index 8c81dcbce7..1a4ad60157 100644 --- a/.github/styles/Microsoft/Contractions.yml +++ b/.github/styles/Microsoft/Contractions.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: substitution message: "Use '%s' instead of '%s'." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-contractions diff --git a/.github/styles/Microsoft/Dashes.yml b/.github/styles/Microsoft/Dashes.yml.disabled similarity index 96% rename from .github/styles/Microsoft/Dashes.yml rename to .github/styles/Microsoft/Dashes.yml.disabled index 72b05ba3e5..857d2e9107 100644 --- a/.github/styles/Microsoft/Dashes.yml +++ b/.github/styles/Microsoft/Dashes.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "Remove the spaces around '%s'." link: https://docs.microsoft.com/en-us/style-guide/punctuation/dashes-hyphens/emes diff --git a/.github/styles/Microsoft/DateFormat.yml b/.github/styles/Microsoft/DateFormat.yml.disabled similarity index 56% rename from .github/styles/Microsoft/DateFormat.yml rename to .github/styles/Microsoft/DateFormat.yml.disabled index 196531394a..b52b16b064 100644 --- a/.github/styles/Microsoft/DateFormat.yml +++ b/.github/styles/Microsoft/DateFormat.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: Use 'July 31, 2016' format, not '%s'. link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms @@ -5,4 +6,6 @@ ignorecase: true level: error nonword: true tokens: - - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}' + - '\d{1,2} + (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) + \d{4}' diff --git a/.github/styles/Microsoft/Ellipses.yml b/.github/styles/Microsoft/Ellipses.yml.disabled similarity index 95% rename from .github/styles/Microsoft/Ellipses.yml rename to .github/styles/Microsoft/Ellipses.yml.disabled index 320457a8bc..d84dec60c0 100644 --- a/.github/styles/Microsoft/Ellipses.yml +++ b/.github/styles/Microsoft/Ellipses.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "In general, don't use an ellipsis." link: https://docs.microsoft.com/en-us/style-guide/punctuation/ellipses diff --git a/.github/styles/Microsoft/FirstPerson.yml b/.github/styles/Microsoft/FirstPerson.yml.disabled similarity index 96% rename from .github/styles/Microsoft/FirstPerson.yml rename to .github/styles/Microsoft/FirstPerson.yml.disabled index f58dea3142..e40e46b9b7 100644 --- a/.github/styles/Microsoft/FirstPerson.yml +++ b/.github/styles/Microsoft/FirstPerson.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "Use first person (such as '%s') sparingly." link: https://docs.microsoft.com/en-us/style-guide/grammar/person diff --git a/.github/styles/Microsoft/Foreign.yml b/.github/styles/Microsoft/Foreign.yml.disabled similarity index 97% rename from .github/styles/Microsoft/Foreign.yml rename to .github/styles/Microsoft/Foreign.yml.disabled index 0d3d6002a9..b40abf1f54 100644 --- a/.github/styles/Microsoft/Foreign.yml +++ b/.github/styles/Microsoft/Foreign.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: substitution message: "Use '%s' instead of '%s'." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words diff --git a/.github/styles/Microsoft/GeneralURL.yml b/.github/styles/Microsoft/GeneralURL.yml.disabled similarity index 96% rename from .github/styles/Microsoft/GeneralURL.yml rename to .github/styles/Microsoft/GeneralURL.yml.disabled index dcef503d99..239ed06490 100644 --- a/.github/styles/Microsoft/GeneralURL.yml +++ b/.github/styles/Microsoft/GeneralURL.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "For a general audience, use 'address' rather than 'URL'." link: https://docs.microsoft.com/en-us/style-guide/urls-web-addresses diff --git a/.github/styles/Microsoft/HeadingAcronyms.yml b/.github/styles/Microsoft/HeadingAcronyms.yml.disabled similarity index 89% rename from .github/styles/Microsoft/HeadingAcronyms.yml rename to .github/styles/Microsoft/HeadingAcronyms.yml.disabled index 9dc3b6c2de..3ee3b20f9e 100644 --- a/.github/styles/Microsoft/HeadingAcronyms.yml +++ b/.github/styles/Microsoft/HeadingAcronyms.yml.disabled @@ -1,7 +1,8 @@ +#disabled extends: existence message: "Avoid using acronyms in a title or heading." link: https://docs.microsoft.com/en-us/style-guide/acronyms#be-careful-with-acronyms-in-titles-and-headings level: warning scope: heading tokens: - - '[A-Z]{2,4}' + - "[A-Z]{2,4}" diff --git a/.github/styles/Microsoft/Headings.yml.disabled b/.github/styles/Microsoft/Headings.yml.disabled new file mode 100644 index 0000000000..c5746b2be1 --- /dev/null +++ b/.github/styles/Microsoft/Headings.yml.disabled @@ -0,0 +1 @@ +#copied to Graphile/Headings.yml diff --git a/.github/styles/Microsoft/Hyphens.yml b/.github/styles/Microsoft/Hyphens.yml index 7e5731c995..5346c6265c 100644 --- a/.github/styles/Microsoft/Hyphens.yml +++ b/.github/styles/Microsoft/Hyphens.yml @@ -12,3 +12,5 @@ action: - " " tokens: - '\b[^\s-]+ly-\w+\b' +exceptions: + - strongly-typed diff --git a/.github/styles/Microsoft/Passive.yml b/.github/styles/Microsoft/Passive.yml.disabled similarity index 99% rename from .github/styles/Microsoft/Passive.yml rename to .github/styles/Microsoft/Passive.yml.disabled index 102d377cac..d6f6210fa0 100644 --- a/.github/styles/Microsoft/Passive.yml +++ b/.github/styles/Microsoft/Passive.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "'%s' looks like passive voice." ignorecase: true diff --git a/.github/styles/Microsoft/Quotes.yml b/.github/styles/Microsoft/Quotes.yml index 38f4976061..37fb92a72d 100644 --- a/.github/styles/Microsoft/Quotes.yml +++ b/.github/styles/Microsoft/Quotes.yml @@ -1,5 +1,5 @@ extends: existence -message: 'Punctuation should be inside the quotes.' +message: "Punctuation should be inside the quotes." link: https://docs.microsoft.com/en-us/style-guide/punctuation/quotation-marks level: error nonword: true diff --git a/.github/styles/Microsoft/Semicolon.yml b/.github/styles/Microsoft/Semicolon.yml.disabled similarity index 91% rename from .github/styles/Microsoft/Semicolon.yml rename to .github/styles/Microsoft/Semicolon.yml.disabled index 4d905467dd..29a87258ba 100644 --- a/.github/styles/Microsoft/Semicolon.yml +++ b/.github/styles/Microsoft/Semicolon.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "Try to simplify this sentence." link: https://docs.microsoft.com/en-us/style-guide/punctuation/semicolons @@ -5,4 +6,4 @@ nonword: true scope: sentence level: suggestion tokens: - - ';' + - ";" diff --git a/.github/styles/Microsoft/SentenceLength.yml b/.github/styles/Microsoft/SentenceLength.yml.disabled similarity index 92% rename from .github/styles/Microsoft/SentenceLength.yml rename to .github/styles/Microsoft/SentenceLength.yml.disabled index f248cf0513..7beea91888 100644 --- a/.github/styles/Microsoft/SentenceLength.yml +++ b/.github/styles/Microsoft/SentenceLength.yml.disabled @@ -1,7 +1,7 @@ +#disabled extends: occurrence message: "Try to keep sentences short (< 30 words)." scope: sentence level: suggestion max: 30 token: \b(\w+)\b - diff --git a/.github/styles/Microsoft/Spacing.yml b/.github/styles/Microsoft/Spacing.yml index bbd10e51df..da4fc874f9 100644 --- a/.github/styles/Microsoft/Spacing.yml +++ b/.github/styles/Microsoft/Spacing.yml @@ -4,5 +4,5 @@ link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods level: error nonword: true tokens: - - '[a-z][.?!] {2,}[A-Z]' - - '[a-z][.?!][A-Z]' + - "[a-z][.?!] {2,}[A-Z]" + - "[a-z][.?!][A-Z]" #disabled as some headings use methods diff --git a/.github/styles/Microsoft/Vocab.yml b/.github/styles/Microsoft/Vocab.yml.disabled similarity index 83% rename from .github/styles/Microsoft/Vocab.yml rename to .github/styles/Microsoft/Vocab.yml.disabled index eebe97b15e..e401ed79eb 100644 --- a/.github/styles/Microsoft/Vocab.yml +++ b/.github/styles/Microsoft/Vocab.yml.disabled @@ -1,6 +1,7 @@ +#disabled extends: existence message: "Verify your use of '%s' with the A-Z word list." -link: 'https://docs.microsoft.com/en-us/style-guide' +link: "https://docs.microsoft.com/en-us/style-guide" level: suggestion ignorecase: true tokens: diff --git a/.github/styles/Microsoft/We.yml b/.github/styles/Microsoft/We.yml.disabled similarity index 96% rename from .github/styles/Microsoft/We.yml rename to .github/styles/Microsoft/We.yml.disabled index 97c901c1ba..ac1ffbc0b7 100644 --- a/.github/styles/Microsoft/We.yml +++ b/.github/styles/Microsoft/We.yml.disabled @@ -1,3 +1,4 @@ +#disabled extends: existence message: "Try to avoid using first-person plural like '%s'." link: https://docs.microsoft.com/en-us/style-guide/grammar/person#avoid-first-person-plural diff --git a/.github/styles/config/vocabularies/Graphile/accept.txt b/.github/styles/config/vocabularies/Graphile/accept.txt new file mode 100644 index 0000000000..53d252ec13 --- /dev/null +++ b/.github/styles/config/vocabularies/Graphile/accept.txt @@ -0,0 +1,21 @@ +tamedevil +performant +substring +autofix +ESLint +[Gg]raphile +[Gg]rafast +PostGraphile +middleware +[Cc]onfig +Gra +[Ee]val +EXPORTABLEs +untrusted +PostGraphQL +subcommand +namespace +booleans +preprocessor +unformatted +autofixed diff --git a/.github/styles/config/vocabularies/Graphile/reject.txt b/.github/styles/config/vocabularies/Graphile/reject.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/.vale.ini b/.vale.ini index 02b49b2acd..482b5fedf6 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,7 @@ StylesPath = .github/styles +Vocab = Graphile + MinAlertLevel = suggestion Packages = Microsoft, MDX @@ -14,4 +16,4 @@ Packages = Microsoft, MDX # Markdown and reStructuredText: # # [*.{md,rst}] -BasedOnStyles = Vale, Microsoft +BasedOnStyles = Vale, Microsoft, Graphile diff --git a/utils/website/graphile-config/preset.md b/utils/website/graphile-config/preset.md index 167a605c27..6d31349f16 100644 --- a/utils/website/graphile-config/preset.md +++ b/utils/website/graphile-config/preset.md @@ -3,7 +3,7 @@ sidebar_position: 2 title: Preset --- -# GraphileConfig.Preset +# `GraphileConfig.Preset` _Target Audience: all Graphile Config users ⚙️🔌📚_ @@ -208,7 +208,7 @@ following implications: :::warning Order of composition is important -Consider a preset, APreset, that extends two other presets: Preset1 and Preset2, +Consider a preset, `APreset`, that extends two other presets: Preset1 and Preset2, each of which `extends` the same preset, Preset0: ```ts @@ -218,7 +218,7 @@ const Preset2 = { extends: [Preset0], myScope: { option2: true } }; const APreset = { extends: [Preset1, Preset2] }; ``` -Any overrides to the options set in Preset0 by Preset1 will be reset in APreset +Any overrides to the options set in Preset0 by Preset1 will be reset in `APreset` since they will be overridden when Preset2 applies the Preset0 options again: ```ts diff --git a/utils/website/graphile-export/exportable.md b/utils/website/graphile-export/exportable.md index cf88381622..83db1f8871 100644 --- a/utils/website/graphile-export/exportable.md +++ b/utils/website/graphile-export/exportable.md @@ -8,7 +8,7 @@ made in such a way that it can work with Graphile Export. This applies both to the parts of the schema you write yourself, and the parts you may import from external libraries. -Generally speaking there are 2 methods of acheiving this, used in unison: +Generally speaking there are 2 methods of achieving this, used in unison: 1. All non-pure functions and their non-trivial scope dependencies must be made exportable by wrapping in an `EXPORTABLE()` call, or be made importable via @@ -262,7 +262,7 @@ export const preset: GraphileConfig.Preset = { ## Troubleshooting -### undefined variable `EXPORTABLE` +### `undefined variable EXPORTABLE` Our ESLint plugin isn't smart enough to actually `import` the `EXPORTABLE` helper, so after running the autofix you might end up with "undefined variable diff --git a/utils/website/pg-sql2/index.md b/utils/website/pg-sql2/index.md index 81f3ffbd04..fc41f943a0 100644 --- a/utils/website/pg-sql2/index.md +++ b/utils/website/pg-sql2/index.md @@ -69,4 +69,4 @@ This is a replacement for [@calebmer's pg-sql](https://www.npmjs.com/package/pg- - Better development experience for people not using TypeScript (throws errors a lot earlier allowing you to catch issues at the source) - Slightly more helpful error messages - Uses a symbol-key on the query nodes to protect against an object accidentally being inserted verbatim and being treated as valid (because every Symbol is unique an attacker would need control of the code to get a reference to the Symbol in order to set it on an object (it cannot be serialised/deserialised via JSON or any other medium), and if the attacker has control of the code then you've already lost) -- Adds `sql.literal` which is similar to `sql.value` but when used with simple values can write the valid direct to the SQL statement. **USE WITH CAUTION**. The purpose for this is if you are using _trusted_ values (e.g. for the keys to [`json_build_object(...)`](https://www.postgresql.org/docs/9.6/static/functions-json.html)) then debugging your SQL becomes a lot easier because fewer placeholders are used. +- Adds `sql.literal` which is similar to `sql.value` but when used with simple values can write the valid direct to the SQL statement. **Use with caution**. The purpose for this is if you are using _trusted_ values (e.g. for the keys to [`json_build_object(...)`](https://www.postgresql.org/docs/9.6/static/functions-json.html)) then debugging your SQL becomes a lot easier because fewer placeholders are used. diff --git a/utils/website/tamedevil/api/te-safe-key-or-throw.md b/utils/website/tamedevil/api/te-safe-key-or-throw.md index df50a70d67..7c20defed2 100644 --- a/utils/website/tamedevil/api/te-safe-key-or-throw.md +++ b/utils/website/tamedevil/api/te-safe-key-or-throw.md @@ -20,5 +20,5 @@ this is intended to be used with relatively straightforward strings `const obj = { ${te.safeKeyOrThrow(untrustedKey)}: value }` you instead use `const obj = Object.create(null);` and then set the properties on the resulting object via `${obj}[${te.lit(untrustedKey)}] = value;` - this prevents attacks -such as **prototype polution** since properties like `__proto__` are not special -on null-prototype objects, whereas they can cause havok in regular `{}` objects. +such as **prototype pollution** since properties like `__proto__` are not special +on null-prototype objects, whereas they can cause havoc in regular `{}` objects. diff --git a/utils/website/tamedevil/index.md b/utils/website/tamedevil/index.md index cd061a9931..89b914a08c 100644 --- a/utils/website/tamedevil/index.md +++ b/utils/website/tamedevil/index.md @@ -8,7 +8,7 @@ title: tamedevil **Eval is evil, this module helps tame it!** It's generally recommended that you don't use `eval` or `new Function` when -writing JavaScript/TypeScript code. There's many many reasons for this, here are +writing JavaScript/TypeScript code. There's many reasons for this, here are but a few: - **code injection**: without sufficient caution, attackers could inject @@ -23,7 +23,7 @@ but a few: However, `eval` and `new Function` can be powerful tools for building performant code - if you have a list of operations to perform, it may be much more performant to build a dynamic function to evaluate those operations at native JS -speed rather than to build your own interpretter. +speed rather than to build your own interpreter. `tamedevil` makes it much safer to build this kind of dynamic function, by ensuring that every string and substring that is to be evaluated is either code