Repository navigation
Conversation
Adds a Checkly Vale style (check and monitor types, third-party names, single feature instances) and a script that checks headings, frontmatter titles and component titles for sentence case. Both run only on the lines a PR adds or changes, so existing text never fails a PR. The rules are in AGENTS.md under "Casing and terminology"; run them locally with npm run lint:casing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · The check's logic is sound. Resolve the merge conflict with main's anchor check, and fix the one rule that suggests the wrong replacement.
Blocker: merge conflict. GitHub reports CONFLICTING. Since the merge base (d7a8349b), main landed 96f0763d ("ci: fail PRs on links to missing #anchors"). That commit inserts the Test anchor checker and Broken-anchors scan steps right where this PR adds Casing check in .github/workflows/static-docs-checks.yml. It also adds check:anchors/test:anchors next to this PR's lint:casing in package.json. Keep both sides in both files.
CI hasn't exercised the rules yet. In this PR's static-docs-checks run, the Casing check step downloaded Vale 3.25.1 fine, then printed "Casing check: no changed .mdx lines to check." The PR changes no .mdx file, so the green check says nothing about the rules. The PR description lists local runs (a sample page, #774, today's open PRs). The other gate scripts on main ship with node --test suites (test:anchors, test:css-urls, test:api-docs). This one becomes a required check that blocks PRs, so consider a small fixture test for the sentence-case function and one Vale rule per file. Optional, but it keeps a regex change from silently blocking every PR.
What I checked in the logic, all fine:
- Changed-line detection parses
git diff --unified=0hunk headers from the merge base. Pure deletions add no lines.fetch-depth: 0in the workflow makesmerge-base "$BASE_SHA" HEADresolvable. api-reference/andapi-reference-old/are skipped.- Frontmatter and fenced code are skipped for Vale, and matches inside
**bold**, inline code, and quotes are dropped. .github/vale/checkly.iniruns onlyBasedOnStyles = Checklyfrom../../styles. The repo's.vale.ininames its styles explicitly (Vale, Google, proselint, write-good, alex), so the newstyles/Checkly/folder doesn't change the existing Vale runs.- The
$1replacements inFeatureInstances.ymlare supported (Vale substitution docs). - A match that already equals its replacement raises no alert, so
'Open ?[Tt]elemetry'doesn't flag a correct "OpenTelemetry". See thesame/matchTokencheck ininternal/check/substitution.go.
Inline: 1 Important, 1 Wording.
What I checked
- Read every file in the diff from merge base
d7a8349bwithgit show/git diff:check-casing.mjs,checkly.ini, the workflow,AGENTS.md,package.json,Brands.yml,CheckTypes.yml,FeatureInstances.yml, andproper-nouns.txt. I did not run any code from the PR. git diff <base> origin/mainon the touched files: only96f0763d, which changed the workflow andpackage.json.gh pr checks 775: all pass, and vale-spellcheck was skipped. Read thestatic-docs-checkslog for the Casing check step.origin/main:.vale.iniand the existingstyles/tree.- Vale docs and source for substitution capture groups and the skip-when-equal check (links above).
- Could not verify: the false-positive rate on real
.mdxchanges. I relied on the PR description's local runs, since CI had no.mdxto check.
| swap: | ||
| '(?:Browser|browser) Checks': Browser checks | ||
| '(?:Browser|browser) Check': Browser check | ||
| 'browser checks?(?= (?:in|on|with|run|that|for)\b)': Browser check |
There was a problem hiding this comment.
Important: the optional s? makes this rule suggest the singular for plurals. With ignorecase: false and a literal replacement, "browser checks in…" produces "Use 'Browser check' instead of 'browser checks'", and an author who applies it verbatim drops the plural. The other type rules list the plural and singular as separate entries, so do the same here:
| 'browser checks?(?= (?:in|on|with|run|that|for)\b)': Browser check | |
| 'browser checks(?= (?:in|on|with|run|that|for)\b)': Browser checks | |
| 'browser check(?= (?:in|on|with|run|that|for)\b)': Browser check |
| 'OpsGenie': Opsgenie | ||
| 'Pagerduty|PagerDUTY': PagerDuty | ||
| 'Hashicorp': HashiCorp | ||
| 'Kubernetes(?=s)|kubernetes(?= (?:cluster|deployment|pod))': Kubernetes |
There was a problem hiding this comment.
Wording (optional): the first alternative, Kubernetes(?=s), can never raise an alert. It only matches when the text already reads "Kubernetes", and Vale skips a match that equals its replacement. Only the lowercase alternative does anything. If that's the intent, drop the dead part:
| 'Kubernetes(?=s)|kubernetes(?= (?:cluster|deployment|pod))': Kubernetes | |
| 'kubernetes(?= (?:cluster|deployment|pod))': Kubernetes |
Keep main's anchor checks and add the Casing check step before them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WL5whrFpHCtRKygwuMxU8e
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WL5whrFpHCtRKygwuMxU8e
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · The merge conflict from the last review is resolved. One small fix is left: the browser checks? rule still suggests the singular for plurals. Apply the existing suggestion and this is ready.
This review covers the commits since d7266899 (the SHA I reviewed on Nov 3). The branch merged main in 78248eb9, so I compared the full diff from the new merge base (15169559) with the previous review instead of reading main's changes as part of this PR.
Resolved since the last review
- Merge conflict: fixed.
gh pr viewnow reportsMERGEABLE/CLEAN. In.github/workflows/static-docs-checks.ymlthe merge keepsmain's Test anchor checker and Broken-anchors scan steps after Casing check. Inpackage.jsonit keepscheck:anchorsandtest:anchorsnext tolint:casing. Nothing frommainwas dropped. Brontoadded tostyles/Checkly/proper-nouns.txt. That matches the Bronto trace export page that landed onmainin #833, so headings that name Bronto don't fail the sentence-case check.
Still open from the last review (the lines are unchanged, so the earlier threads still sit on them):
- Important:
styles/Checkly/CheckTypes.ymlline 10,'browser checks?(?= …)': Browser check, tells an author to replace "browser checks" with "Browser check". The one-click suggestion is in this thread: split it into a plural entry and a singular entry, as the other type rules do. - Wording (optional):
styles/Checkly/Brands.ymlline 16, theKubernetes(?=s)alternative can never raise an alert (thread). - Optional: there is still no
node --testsuite forcheck-casing.mjs, unlike the anchor, CSS-URL, and API-navigation checks onmain.
New, optional: Casing check now runs before Test anchor checker, Broken-anchors scan, and Broken-links scan in the same job. Their if: conditions have no status function, so GitHub Actions adds an implicit success() (docs). On a PR with a casing mistake, the anchor and link scans are skipped, and the author learns about broken links only after a second push. Two ways to fix it: move Casing check to the end of the job, or give the scans if: ${{ !cancelled() && steps.detect.outputs.docs_changed == 'true' }}.
Inline: none new. The two open items are the existing threads linked above.
What I checked
git log d7266899..49f0ad10: one merge ofmain(78248eb9) and one PR commit (49f0ad10, Bronto proper noun).git diff d7266899 49f0ad10on the PR's own files (check-casing.mjs,checkly.ini, the workflow,AGENTS.md,package.json,styles/Checkly/*). Only the workflow,package.json, andproper-nouns.txtchanged, all as described above.git diff --stat 15169559 refs/pr-775: the PR still touches the same 9 files as before (519 additions in total), and nothing outside them.- Read the full workflow and
CheckTypes.yml/Brands.ymlat the head. Lines 10 and 16 are unchanged. gh pr checks 775: static-docs-checks, docs-gate, preview-checks, link-rot, and Mintlify Deployment pass. vale-spellcheck and reindex were skipped.gh pr view 775 --json mergeable,mergeStateStatus:MERGEABLE,CLEAN.- Overlap: draft #848 also adds lines to
AGENTS.md, so whichever lands second may need a rebase there. #774 (sentence case) is the content this check is meant to keep in place, and either can land first. - I did not run any code from the PR.
Adds a casing check to
static-docs-checksthat fails a PR when a line it adds or changes breaks the docs casing rules. Existing text elsewhere in a file never fails the check.Rules (also in
AGENTS.mdunder "Casing and terminology", so agents follow them while writing):title/sidebarTitleand componenttitle="…"use sentence case. Acronyms and mixed-case names pass; other names that keep their capitals are listed instyles/Checkly/proper-nouns.txt.How: a
styles/ChecklyVale style for the term rules, and.github/scripts/check-casing.mjsfor sentence case. Run it locally withnpm run lint:casing, ornpm run lint:casing -- --all <file.mdx>for whole files.Tested:
🤖 Generated with Claude Code