Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 196 additions & 0 deletions .github/scripts/check-casing.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
#!/usr/bin/env node
// Casing check for docs pages (.mdx). Blocks PRs on new casing mistakes.
//
// node .github/scripts/check-casing.mjs lines changed since the merge base with origin/main
// node .github/scripts/check-casing.mjs --base <ref> lines changed since <ref>
// node .github/scripts/check-casing.mjs --all <file.mdx>... every line of the given files
//
// Two kinds of rules, both described in AGENTS.md ("Casing and terminology"):
// - Vale, with only the Checkly style (styles/Checkly/*.yml): check and monitor
// types, third-party names, single feature instances.
// - This script: headings, frontmatter `title`/`sidebarTitle` and component
// `title="…"` props use sentence case. Names that keep their capitals are in
// styles/Checkly/proper-nouns.txt.
//
// Only changed lines are checked by default, so existing text never blocks a PR.
// Files under api-reference/ (generated) and api-reference-old/ (legacy) are skipped.

import { execFileSync } from 'node:child_process'
import { readFileSync, existsSync } from 'node:fs'
import path from 'node:path'

const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim()
process.chdir(root)

const args = process.argv.slice(2)
const all = args.includes('--all')
const baseIdx = args.indexOf('--base')
const base = baseIdx >= 0 ? args[baseIdx + 1] : process.env.CASING_BASE || 'origin/main'
const norm = (f) => path.relative(root, path.resolve(root, f))
const isDoc = (f) => f.endsWith('.mdx') && !/^api-reference(-old)?\//.test(norm(f)) && existsSync(f)

// file -> Set of line numbers to check (null = every line)
const targets = new Map()
if (all) {
for (const f of args.filter((a) => a !== '--all' && a !== '--base' && a !== base)) {
if (isDoc(f)) targets.set(norm(f), null)
}
} else {
const mergeBase = execFileSync('git', ['merge-base', base, 'HEAD'], { encoding: 'utf8' }).trim()
const diff = execFileSync('git', ['diff', '--unified=0', '--no-color', mergeBase, '--', '*.mdx'], {
encoding: 'utf8',
maxBuffer: 256 * 1024 * 1024,
})
let file = null
for (const line of diff.split('\n')) {
if (line.startsWith('+++ ')) {
const f = line.slice(4).replace(/^b\//, '')
file = isDoc(f) ? f : null
if (file && !targets.has(file)) targets.set(file, new Set())
continue
}
const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
if (hunk && file) {
const start = Number(hunk[1])
const count = hunk[2] === undefined ? 1 : Number(hunk[2])
for (let i = 0; i < count; i++) targets.get(file).add(start + i)
}
}
for (const [f, lines] of targets) if (lines.size === 0) targets.delete(f)
}

if (targets.size === 0) {
console.log('Casing check: no changed .mdx lines to check.')
process.exit(0)
}

const problems = []
const wanted = (file, line) => {
const lines = targets.get(file)
return lines === null || lines.has(line)
}

// 1. Vale with the Checkly style only.
const valeConfig = path.join(root, '.github/vale/checkly.ini')
let valeOut = '{}'
try {
valeOut = execFileSync('vale', [`--config=${valeConfig}`, '--output=JSON', '--no-exit', ...targets.keys()], {
encoding: 'utf8',
maxBuffer: 256 * 1024 * 1024,
})
} catch (err) {
console.error('Casing check: could not run Vale. Install it (https://vale.sh/docs/install) and try again.')
console.error(err.message)
process.exit(2)
}
// Lines Vale must not judge: frontmatter and fenced code (Vale misses fences
// nested in JSX components). Spans inside **bold** UI labels, quotes or inline
// code keep the app's or the code's own casing.
const skipLines = new Map()
for (const file of targets.keys()) {
const set = new Set()
let fence = false
let fm = false
readFileSync(file, 'utf8').split('\n').forEach((raw, idx) => {
const n = idx + 1
if (idx === 0 && raw.trim() === '---') { fm = true; set.add(n); return }
if (fm) { set.add(n); if (raw.trim() === '---') fm = false; return }
if (/^\s*(```|~~~)/.test(raw)) { fence = !fence; set.add(n); return }
if (fence) set.add(n)
})
skipLines.set(file, set)
}
const insideMarkup = (text, start, end) => {
for (const re of [/\*\*[^*]+\*\*/g, /`[^`]+`/g, /"[^"]*"/g, /“[^”]*”/g]) {
for (const m of text.matchAll(re)) if (m.index <= start && m.index + m[0].length >= end) return true
}
return false
}
const fileLines = new Map([...targets.keys()].map((f) => [f, readFileSync(f, 'utf8').split('\n')]))
for (const [valeFile, alerts] of Object.entries(JSON.parse(valeOut || '{}'))) {
const file = norm(valeFile)
if (!targets.has(file)) continue
for (const a of alerts) {
if (!wanted(file, a.Line) || skipLines.get(file).has(a.Line)) continue
const text = fileLines.get(file)[a.Line - 1] || ''
if (insideMarkup(text, a.Span[0] - 1, a.Span[1])) continue
problems.push({ file, line: a.Line, rule: a.Check, message: a.Message })
}
}

// 2. Sentence case for headings and titles.
const nouns = readFileSync('styles/Checkly/proper-nouns.txt', 'utf8')
.split('\n')
.map((l) => l.trim())
.filter((l) => l && !l.startsWith('#'))
.sort((a, b) => b.length - a.length)
const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
const nounRe = nouns.length ? new RegExp(`(?<![\\w-])(?:${nouns.map(escape).join('|')})(?![\\w-])`, 'g') : null

function titleCaseWords(text) {
let t = text
.replace(/`[^`]*`/g, ' ') // inline code
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links: keep the text
.replace(/[*_]{1,3}/g, '') // emphasis
.replace(/<[^>]+>/g, ' ') // inline tags
.replace(/\{[^}]*\}/g, ' ') // expressions
.replace(/"[^"]*"|“[^”]*”|'[^']*'(?!\w)/g, ' ') // quoted UI labels and error messages
if (nounRe) t = t.replace(nounRe, ' ')
const bad = []
// Split into clauses: the first word after a colon, a sentence end or a
// numbering like "Step 2:" may be capitalized.
for (const clause of t.split(/[:.!?]\s+|\s[–—|-]\s/)) {
const words = clause.trim().split(/\s+/).filter((w) => /[\p{L}\d]/u.test(w))
words.forEach((w, i) => {
if (i === 0) return
const word = w.replace(/^[("'“‘]+|[)"'”’,;!?.]+$/g, '')
// Plain capitalized words only: acronyms (RCA), mixed case (gRPC,
// OpenTelemetry) and words with digits are fine.
if (/^[A-Z][a-z]+(?:['’]s)?$/.test(word)) bad.push(word)
})
}
return bad
}

for (const file of targets.keys()) {
const lines = readFileSync(file, 'utf8').split('\n')
let inFence = false
let inFrontmatter = false
lines.forEach((raw, idx) => {
const n = idx + 1
if (idx === 0 && raw.trim() === '---') return void (inFrontmatter = true)
if (inFrontmatter) {
if (raw.trim() === '---') return void (inFrontmatter = false)
const fm = raw.match(/^(title|sidebarTitle):\s*(['"]?)(.*)\2\s*$/)
if (fm && wanted(file, n)) {
const bad = titleCaseWords(fm[3])
if (bad.length) problems.push({ file, line: n, rule: 'Checkly.SentenceCase', message: `Use sentence case for ${fm[1]} '${fm[3]}' (${bad.join(', ')}). If it's a name, add it to styles/Checkly/proper-nouns.txt.` })
}
return
}
if (/^\s*(```|~~~)/.test(raw)) return void (inFence = !inFence)
if (inFence || !wanted(file, n)) return
const heading = raw.match(/^\s{0,3}#{1,6}\s+(.*?)\s*#*\s*$/)
if (heading) {
const bad = titleCaseWords(heading[1])
if (bad.length) problems.push({ file, line: n, rule: 'Checkly.SentenceCase', message: `Use sentence case for the heading '${heading[1]}' (${bad.join(', ')}). If it's a name, add it to styles/Checkly/proper-nouns.txt.` })
}
for (const m of raw.matchAll(/<(Card|Step|Tab|Accordion|Expandable|Update)\b[^>]*\btitle="([^"]+)"/g)) {
const bad = titleCaseWords(m[2])
if (bad.length) problems.push({ file, line: n, rule: 'Checkly.SentenceCase', message: `Use sentence case for the ${m[1]} title '${m[2]}' (${bad.join(', ')}). If it's a name, add it to styles/Checkly/proper-nouns.txt.` })
}
})
}

problems.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
for (const p of problems) {
if (process.env.GITHUB_ACTIONS) console.log(`::error file=${p.file},line=${p.line},title=${p.rule}::${p.message}`)
console.log(`${p.file}:${p.line} ${p.rule} ${p.message}`)
}
const checked = [...targets.values()].reduce((n, s) => n + (s === null ? 0 : s.size), 0)
console.log(
problems.length
? `\nCasing check: ${problems.length} problem(s). The rules are in AGENTS.md under "Casing and terminology".`
: `Casing check: OK (${targets.size} file(s)${all ? '' : `, ${checked} changed line(s)`}).`,
)
process.exit(problems.length ? 1 : 0)
18 changes: 18 additions & 0 deletions .github/vale/checkly.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Vale config for the casing check (.github/scripts/check-casing.mjs).
# Only the Checkly style runs here, so the check blocks on our own rules and
# nothing else. The repo's main .vale.ini keeps the broader writing styles.
StylesPath = ../../styles
MinAlertLevel = error

[formats]
mdx = md

[*.{md,mdx}]
BasedOnStyles = Checkly

[*.mdx]
CommentDelimiters = {/*, */}
TokenIgnores = (?sm)((?:import|export) .+?$), \
(?<!`)(<\w+ ?.+ ?\/>)(?!`)
BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
(?sm)^({.+.*})
14 changes: 14 additions & 0 deletions .github/workflows/static-docs-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,20 @@ jobs:
exit 1
fi

# Blocks casing mistakes in the lines this PR adds or changes: headings
# and titles in sentence case, check and monitor types ("Browser check",
# "URL monitor"), third-party names, single feature instances. Existing
# text elsewhere in a file never fails the check. Rules: AGENTS.md,
# "Casing and terminology"; run locally with `npm run lint:casing`.
- name: Casing check
if: steps.detect.outputs.docs_changed == 'true'
env:
VALE_VERSION: '3.25.1'
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
curl -sSfL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" | tar -xz -C "$RUNNER_TEMP" vale
PATH="$RUNNER_TEMP:$PATH" node .github/scripts/check-casing.mjs --base "$BASE_SHA"

- name: Test anchor checker
run: npm run test:anchors

Expand Down
10 changes: 10 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
# Mintlify documentation

Check warning on line 1 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L1

Did you really mean 'Mintlify'?

## Working relationship
- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
- ALWAYS ask for clarification rather than making assumptions
- NEVER lie, guess, or make up information

Check warning on line 6 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L6

Spell out 'NEVER', if it's unfamiliar to the audience.

## Project context
- Framework: Mintlify. https://mintlify.com/docs/llms.txt

Check warning on line 9 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L9

Did you really mean 'Mintlify'?
- Format: MDX files with YAML frontmatter

Check warning on line 10 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L10

Spell out 'MDX', if it's unfamiliar to the audience.

Check warning on line 10 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L10

Did you really mean 'frontmatter'?
- Config: docs.json for navigation, theme, settings. Tabs set top level navigation, Groups set sidebar navigation within Tabs.

Check warning on line 11 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L11

Did you really mean 'Config'?
- Components: We use Mintlify components and documentation.

Check warning on line 12 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L12

Try to avoid using first-person plural like 'We'.

Check warning on line 12 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L12

Did you really mean 'Mintlify'?
-- Headers and text
-- Images and embeds
-- Lists and tables
-- Code
-- Reusable snippets
-- Accordions
-- Callouts

Check warning on line 19 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L19

Did you really mean 'Callouts'?
-- Cards
-- Columns
-- Code groups
-- Examples
-- Expandables

Check warning on line 24 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L24

Did you really mean 'Expandables'?
-- Fields
-- Frames
-- Icons
Expand All @@ -29,31 +29,31 @@
-- Panel
-- Steps
-- Tabs
-- Tooltips

Check warning on line 32 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L32

Did you really mean 'Tooltips'?
-- Update

## Content strategy
- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason

Check warning on line 36 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L36

Use 'it's' instead of 'it is'.

Check warning on line 36 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L36

'it is' is too wordy.

Check warning on line 36 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L36

'is done' may be passive voice. Use active voice if you can.

Check warning on line 36 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L36

In general, use active voice instead of passive voice ('is done').

Check warning on line 36 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L36

Try to avoid using 'is'.
- Check existing patterns for consistency
- Start by making the smallest reasonable changes
- Document just enough for user success - not too much. Don't be verbose.

Check warning on line 39 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L39

Try to avoid using 'be'.
- Prioritize accuracy and usability of information

Check warning on line 40 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L40

'Prioritize' is too wordy.
- Make content evergreen

## docs.json

Check warning on line 43 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L43

'docs.json' should use sentence-style capitalization.

- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation
- Tabs
-- Groups
--- Pages

## Frontmatter requirements for pages

Check warning on line 50 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L50

Did you really mean 'Frontmatter'?
- title: Clear, descriptive page title
- sidebarTitle: Concise title for sidebar

Check warning on line 52 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L52

Did you really mean 'sidebarTitle'?
- description: Concise summary for SEO/navigation

Check warning on line 53 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L53

Spell out 'SEO', if it's unfamiliar to the audience.

## Writing standards
- Second-person voice ("you")

Check warning on line 56 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L56

Use parentheses judiciously.
- Test all code examples before publishing
- Match style and formatting of existing pages
- Include both basic and advanced use cases
Expand All @@ -61,24 +61,34 @@
- Alt text on all images
- Relative paths for internal links

## Casing and terminology
CI blocks a PR when a line it adds or changes breaks these rules. Run `npm run lint:casing` before you push (it needs [Vale](https://vale.sh/docs/install)); `npm run lint:casing -- --all <file.mdx>` checks whole files.

Check warning on line 65 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L65

Use parentheses judiciously.

Check warning on line 65 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L65

Use semicolons judiciously.

- **Headings and titles use sentence case:** capitalize the first word and names only. This covers Markdown headings, frontmatter `title` and `sidebarTitle`, and `title="…"` on Card, Step, Tab, Accordion, Expandable and Update. Acronyms (API, RCA) and mixed-case names (gRPC, OpenTelemetry) are fine. Other names that keep their capitals are listed in `styles/Checkly/proper-nouns.txt`; add a new name there in the same PR.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Did you really mean 'frontmatter'?

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Use parentheses judiciously.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Spell out 'RCA', if it's unfamiliar to the audience.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Use parentheses judiciously.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Try to avoid using 'are'.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

Try to avoid using 'are'.

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

In general, use active voice instead of passive voice ('are listed').

Check warning on line 67 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L67

'are listed' may be passive voice. Use active voice if you can.
- **Check and monitor types:** capitalize the type, lowercase the generic noun: Browser check, API check, Multistep check, URL monitor, TCP monitor, DNS monitor, ICMP monitor, SSL monitor, gRPC monitor, Traceroute monitor, Heartbeat monitor. Keep "Playwright Check Suite" and "Agentic Check" as they are (product names).

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Did you really mean 'Multistep'?

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Spell out 'DNS', if it's unfamiliar to the audience.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Spell out 'ICMP', if it's unfamiliar to the audience.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Did you really mean 'Traceroute'?

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

'monitor' is too wordy.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Did you really mean 'Agentic'?

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Use 'they're' instead of 'they are'.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Try to avoid using 'are'.

Check warning on line 68 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L68

Use parentheses judiciously.
- **Checkly features:** lowercase a single instance ("a status page", "each private location", "your alert channel"). Capitalize only when the text names the feature itself ("Keep your customers informed with Status Pages"). When in doubt, lowercase.

Check warning on line 69 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L69

Did you really mean 'Checkly'?

Check warning on line 69 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L69

Use parentheses judiciously.

Check warning on line 69 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L69

Commas and periods go inside quotation marks.

Check warning on line 69 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L69

Commas and periods go inside quotation marks.

Check warning on line 69 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L69

Use parentheses judiciously.
- **Third-party names:** official casing, such as GitHub, GitLab, JavaScript, TypeScript, Node.js, OpenTelemetry, Opsgenie, PagerDuty, HashiCorp, Microsoft Teams.

Check warning on line 70 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L70

Did you really mean 'Opsgenie'?
- **Never change** code, commands, URLs, file paths, construct names (`BrowserCheck`) or UI labels quoted exactly as the app shows them (in **bold** or quotes). The check skips those too.

Check warning on line 71 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L71

Use parentheses judiciously.
- The rules live in `styles/Checkly/` (Vale) and `.github/scripts/check-casing.mjs`.

Check warning on line 72 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L72

Use parentheses judiciously.

## Component usage rules
- Use Steps component for sequential procedures sparingly.
- Don't use Cards to display information. Only for navigation on Overview type pages
- Use CodeGroups and Dropdowns for code examples that show the same example in different languages
- Use Note/Tip/Warning callouts appropriately

Check warning on line 78 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L78

Did you really mean 'callouts'?

## Code snippet typecheck

Check warning on line 80 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L80

Did you really mean 'typecheck'?
CI typechecks Checkly CLI snippets in `.mdx` files against the latest `checkly` release. Run it locally with `npm run check:snippets`.

Check warning on line 81 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L81

Did you really mean 'typechecks'?

Check warning on line 81 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L81

Did you really mean 'Checkly'?

Check warning on line 81 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L81

Use 'command-line tool' instead of 'CLI'.

Check warning on line 81 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L81

Avoid time-based words like 'latest' in product documentation.

- Complete snippets (with a `checkly` import or `require`) and fragments that use a checkly export (`new ApiCheck(`, `Frequency.EVERY_5M`) are checked automatically.

Check warning on line 83 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L83

Use parentheses judiciously.

Check warning on line 83 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L83

Did you really mean 'checkly'?

Check warning on line 83 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L83

In general, use active voice instead of passive voice ('are checked').

Check warning on line 83 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L83

Try to avoid using 'are'.

Check warning on line 83 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L83

'are checked' may be passive voice. Use active voice if you can.
- `/* More options... */` marks a shortened snippet. Missing required props are allowed; wrong or unknown props still fail.

Check warning on line 84 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L84

'are allowed' may be passive voice. Use active voice if you can.

Check warning on line 84 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L84

Try to avoid using 'are'.

Check warning on line 84 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L84

In general, use active voice instead of passive voice ('are allowed').
- Add a marker comment on the line before the code fence when you need one:
- `{/* typecheck-wrap: ApiCheck */}`: checks a property fragment like `request: {...}` inside that construct.
- `{/* typecheck-wrap */}`: checks a statement like `export default defineConfig(...)`, adding imports only.
- `{/* typecheck-skip */}`: opts the block out. Use it only when the snippet can't match the latest CLI.

Check warning on line 88 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L88

Avoid time-based words like 'latest' in product documentation.

Check warning on line 88 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L88

Use 'command-line tool' instead of 'CLI'.

## CodeGroup Dropdown

Check warning on line 90 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L90

'CodeGroup Dropdown' should use sentence-style capitalization.
- Use `<CodeGroup dropdown={true}>` for code examples that show the same functionality in different programming languages

Check warning on line 91 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L91

Use 'capability' or 'feature' instead of 'functionality'.
- The dropdown automatically creates a language selector based on the code block language identifiers
- Example usage:

Expand All @@ -98,14 +108,14 @@
- Any change under `guides/`, `samples/guides/`, or `images/guides/` follows the `guide-authoring` skill in `.claude/skills/guide-authoring/SKILL.md`: agent path first, tested samples, real screenshots, brand diagrams.

## Git workflow
- NEVER use --no-verify when committing

Check warning on line 111 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L111

Spell out 'NEVER', if it's unfamiliar to the audience.
- Ask how to handle uncommitted changes before starting
- Create a new branch when no clear branch exists for changes
- Commit frequently throughout development
- NEVER skip or disable pre-commit hooks

Check warning on line 115 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L115

Spell out 'NEVER', if it's unfamiliar to the audience.

Check warning on line 115 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L115

Use 'turn off' or 'off' instead of 'disable'.

## Do not

Check warning on line 117 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L117

Use 'don't' instead of 'Do not'.
- Skip frontmatter on any MDX file

Check warning on line 118 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L118

Did you really mean 'frontmatter'?

Check warning on line 118 in AGENTS.md

View check run for this annotation

Mintlify / Mintlify Validation (checkly-422f444a) - vale-spellcheck

AGENTS.md#L118

Spell out 'MDX', if it's unfamiliar to the audience.
- Use absolute URLs for internal links
- Include untested code examples
- Make assumptions - always ask for clarification
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"check:anchors": "node .github/scripts/check-anchors.mjs",
"test:anchors": "node --test .github/scripts/check-anchors.test.mjs",
"check:links": "node .github/scripts/check-broken-links.mjs",
"lint:casing": "node .github/scripts/check-casing.mjs",
"check:snippets": "cd .github/snippet-typecheck && npm update --no-audit --no-fund --silent && npm run check --silent",
"test:snippets": "cd .github/snippet-typecheck && npm update --no-audit --no-fund --silent && npm test --silent",
"test:css-urls": "node --test .github/scripts/check-css-urls.test.mjs",
Expand Down
17 changes: 17 additions & 0 deletions styles/Checkly/Brands.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Third-party and product names use their official casing.
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: false
swap:
'Github': GitHub
'Gitlab': GitLab
'Javascript': JavaScript
'Typescript': TypeScript
'Node(?:JS|js|Js|\.JS)(?! plugin)': Node.js
'Open ?[Tt]elemetry|Opentelemetry': OpenTelemetry
'OpsGenie': Opsgenie
'Pagerduty|PagerDUTY': PagerDuty
'Hashicorp': HashiCorp
'Kubernetes(?=s)|kubernetes(?= (?:cluster|deployment|pod))': Kubernetes

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
'Kubernetes(?=s)|kubernetes(?= (?:cluster|deployment|pod))': Kubernetes
'kubernetes(?= (?:cluster|deployment|pod))': Kubernetes

'MS Teams': Microsoft Teams
38 changes: 38 additions & 0 deletions styles/Checkly/CheckTypes.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Check and monitor types: capitalize the type word, lowercase "check" or "monitor".
# "Playwright Check Suite" and "Agentic Check" are product names and keep their capitals.
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: false
swap:
'(?:Browser|browser) Checks': Browser checks
'(?:Browser|browser) Check': Browser check
'browser checks?(?= (?:in|on|with|run|that|for)\b)': Browser check

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Suggested change
'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

'API Checks': API checks
'API Check': API check
'(?:MultiStep|Multi-step|Multi-Step|multi-step|multistep) checks': Multistep checks
'(?:MultiStep|Multi-step|Multi-Step|multi-step|multistep) check': Multistep check
'Multistep Checks': Multistep checks
'Multistep Check': Multistep check
'URL Monitors': URL monitors
'URL Monitor': URL monitor
'TCP Monitors': TCP monitors
'TCP Monitor': TCP monitor
'DNS Monitors': DNS monitors
'DNS Monitor': DNS monitor
'ICMP Monitors': ICMP monitors
'ICMP Monitor': ICMP monitor
'SSL Monitors': SSL monitors
'SSL Monitor': SSL monitor
'gRPC Monitors': gRPC monitors
'gRPC Monitor': gRPC monitor
'(?:GRPC|Grpc) [Mm]onitors': gRPC monitors
'(?:GRPC|Grpc) [Mm]onitor': gRPC monitor
'(?:Traceroute|traceroute) Monitors': Traceroute monitors
'(?:Traceroute|traceroute) Monitor': Traceroute monitor
'(?:Heartbeat|heartbeat) Monitors': Heartbeat monitors
'(?:Heartbeat|heartbeat) Monitor': Heartbeat monitor
'heartbeat monitors': Heartbeat monitors
'heartbeat monitor': Heartbeat monitor
'Playwright (?:check suites|Check suites|check Suites)': Playwright Check Suites
'Playwright (?:check suite|Check suite|check Suite)': Playwright Check Suite
17 changes: 17 additions & 0 deletions styles/Checkly/FeatureInstances.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# A single instance of a Checkly feature is a common noun: "a status page",
# "each private location". Capitalize a feature only when the text names the
# feature itself ("Keep customers informed with Status Pages"). When in doubt,
# lowercase.
extends: substitution
message: "Use '%s' instead of '%s': it's one instance, not the feature name."
level: error
ignorecase: false
swap:
'\b(a|an|each|every|another|your|this|that) Status Page\b': $1 status page
'\b(a|an|each|every|another|your|this|that) Private Location\b': $1 private location
'\b(a|an|each|every|another|your|this|that) Alert Channel\b': $1 alert channel
'\b(a|an|each|every|another|your|this|that) Check Group\b': $1 check group
'\b(a|an|each|every|another|your|this|that) Maintenance Window\b': $1 maintenance window
'\b(a|an|each|every|another|your|this|that) Test Session\b': $1 test session
'\b(a|an|each|every|another|your|this|that) Environment Variable\b': $1 environment variable
'\b(a|an|each|every|another|your|this|that) Dashboard\b': $1 dashboard
Loading
Loading